This is a pre-alpha version and a work in progress. Features and documentation may not be fully complete. Please use with caution.

TLDR;

Errors

Functions

Todo

Title

Todo

For a more complete List application see https://lists.state-less.cloud

Poll

0
Where can I get this?
0
Meh...
0
Shut up and take my money.

Title

Todo

0
Where can I get this?
0
Meh...
0
Shut up and take my money.

Lifecycle

When you update a server-side state using the setValue function, the component triggers an automatic re-rendering within the client's context. This mechanism ensures that the component promptly notifies subscribed clients about the change, leading to an immediate update in the component's state. Consequently, components rendered on the frontend become reactive, eliminating the necessity for manual refetching or polling of the state.

backend/src/components/Examples.tsx

export const HelloWorldExample2 = () => {
  const [count, setState] = useState(0, { key: "count", scope: "global" });

  const increase = () => {
    setState(count + 1);
  };

  return <ServerSideProps count={count} increase={increase} />;
};

When you invoke the increase function from the client, the server updates the state and triggers a re-render on the client.

export const HelloWorldExample2 = () => {
  const [component, { loading, error }] = useComponent("hello-world-1", {
    client: localClient,
  });
  console.log("HelloWorldExample1", error);
  return (
    <>
      {error && <Alert severity="error">{error.message}</Alert>}
      <Button onClick={() => component?.props?.increase()}>
        Count is {component?.props?.count}
      </Button>
    </>
  );
};

Click the button to observe the count increasing and remaining persistent, even after a page reload. You can also experiment by opening a second tab of the same page and clicking the button. You will notice the count updates simultaneously on both pages.

Errors

Errors thrown within components can propagate back to the client, providing transparency and facilitating efficient debugging processes.

backend/src/components/Examples.tsx

export const HelloWorldExample1 = () => {
  const [count] = useState(0, { key: "count", scope: "global" });

  const increase = () => {
    throw new Error("Not implemented");
  };

  return <ServerSideProps count={count} increase={increase} />;
};

Calling the increase function from the client may result in a server error, which you can handle gracefully in your client-side code. Once a successful function call is made subsequent to the error, the error state is cleared automatically.

frontend/src/server-components/Examples.tsx

const HelloWorldExample1 = () => {
  const [{ count, increase }, { loading, error }] =
    useComponent("hello-world-1");

  return (
    <>
      {error && <Alert severity="error">{error.message}</Alert>}
      <Button onClick={() => increase()} />
    </>
  );
};

Poll Component Example

In this exemplary demonstration, we'll showcase the seamless construction of a poll component using React Server. Our component will facilitate the entire voting process, empowering users to cast their votes for their preferred option effortlessly. With React Server's dynamic capabilities, we'll craft a responsive and interactive poll interface, fostering user engagement and interaction. Let's embark on this enlightening journey to create a poll component that seamlessly integrates with React Server!

Authentication

Don't be alarmed if you encounter an "Not Authorized" error while exploring the poll example. This occurs due to the component's authentication requirement, ensuring secure rendering.

If you prefer to disable authentication, simply remove the authenticate function call within the Poll component. Conversely, if you're keen to delve into authentication, visit the authentication page for clear instructions on implementing server and client-side authentication. It's an intuitive process worth experimenting with!

Backend Code

Let's begin by crafting the backend logic for our poll component. This segment of the code will oversee the state of our poll, enabling users to cast their votes or retract them, if allowed, for the provided options. Additionally, we'll export essential data and functions to the frontend, facilitating seamless display and interaction with the poll.

Insert the backend code here:

import {
    authenticate,
    isClientContext,
    Scopes,
    useState,
} from '@state-less/react-server';
import { JWT_SECRET } from '../config';
import { ServerSideProps } from './ServerSideProps';

export enum PollActions {
    Revert,
}

export const Poll = (
    {
        values,
        key,
        allow = [],
    }: { values: string[]; key: string; allow: PollActions[] },
    { context }
) => {
    if (isClientContext(context)) authenticate(context.headers, JWT_SECRET);
    const [votes, setVotes] = useState(
        values.map(() => 0),
        { key: `votes-${key}`, scope: 'global' }
    );

    const [voted, setVoted] = useState(-1, {
        key: 'voted',
        scope: Scopes.Client,
    });

    const unvote = (index) => {
        if (voted !== index) {
            throw new Error('Already voted');
        }
        const newVotes = [...votes];
        newVotes[index] -= 1;
        setVotes(newVotes);
        setVoted(-1);
    };

    const vote = (index) => {
        if (voted === index && allow.includes(PollActions.Revert)) {
            unvote(index);
            return;
        }
        if (voted !== -1) {
            throw new Error('Already voted');
        }
        const newVotes = [...votes];
        newVotes[index] += 1;
        setVotes(newVotes);
        setVoted(index);
    };

    return (
        <ServerSideProps
            key="poll-props"
            votes={votes}
            values={values}
            voted={voted}
            vote={vote}
        />
    );
};

Frontend Code

With our backend logic in place, let's proceed to develop the frontend component responsible for interfacing with the backend and presenting the poll results. This component will receive essential properties and methods from the backend to showcase the poll options and oversee the user's voting actions.

Insert the frontend code here:

import {
  Alert,
  Box,
  Card,
  IconButton,
  List,
  ListItem,
  ListItemSecondaryAction,
  ListItemText,
} from '@mui/material';
import { useComponent } from '@state-less/react-client';
import HeartIcon from '@mui/icons-material/Favorite';
import { ReactNode } from 'react';

export const Poll = ({
  id = 'poll',
  message,
}: {
  id?: string;
  message?: (props: Record<string, any>) => ReactNode;
}) => {
  const [component, { error, loading }] = useComponent(id, {});
  const sum = component?.props?.votes.reduce((a, b) => a + b, 0);
  return (
    <Card>
      {loading && <Alert severity="info">Loading...</Alert>}
      {error && <Alert severity="error">{error.message}</Alert>}
      {message && message?.(component?.props || {})}
      <List>
        {component?.props?.values?.map((value, i) => {
          const percentage = (100 / sum) * component?.props?.votes[i];
          return (
            <ListItem dense>
              <Box
                sx={{
                  ml: -2,
                  zIndex: 0,
                  position: 'absolute',
                  width: `${percentage}%`,
                  height: `100%`,
                  backgroundColor: 'info.main',
                }}
              />
              <ListItemText
                sx={{ zIndex: 0 }}
                primary={value}
                secondary={component?.props?.votes[i]}
              />
              <ListItemSecondaryAction>
                <IconButton
                  onClick={() => component?.props?.vote(i)}
                  disabled={
                    component?.props?.voted > -1 &&
                    component?.props?.voted !== i
                  }
                  color={component.props.voted === i ? 'primary' : 'default'}
                >
                  <HeartIcon />
                </IconButton>
              </ListItemSecondaryAction>
            </ListItem>
          );
        })}
      </List>
    </Card>
  );
};

Now that both the backend and frontend components are set up, you're ready to integrate the poll component into your application. With React Server managing the poll's state, the voting process seamlessly integrates into your application, providing users with a smooth and interactive experience.

Todo List

Let's embark on creating a Todo App example to illustrate the power of React Server in crafting functional and interactive applications.

For building this project yourself, ensure you have Material UI installed to leverage its components effectively.

yarn add @mui/material @mui/icons-material
yarn add @emotion/react @emotion/styled

backend/src/components/Todos.tsx

import { Scopes, useState } from '@state-less/react-server';
import { v4 } from 'uuid';
import { ServerSideProps } from './ServerSideProps';

type TodoObject = {
    id: string | null;
    title: string;
    completed: boolean;
};

export const Todo = ({ id, completed, title }: TodoObject) => {
    const [todo, setTodo] = useState<TodoObject>(
        {
            id,
            completed,
            title,
        },
        {
            key: `page${id}`,
            scope: Scopes.Client,
        }
    );

    const toggle = () => {
        setTodo({ ...todo, completed: !todo.completed });
    };

    return <ServerSideProps key={`${id}-todo`} {...todo} toggle={toggle} />;
};

export const Todos = () => {
    const [todos, setTodos] = useState<TodoObject[]>([], {
        key: 'todos',
        scope: Scopes.Client,
    });

    const addTodo = (todo: TodoObject) => {
        const id = v4();
        const newTodo = { ...todo, id };

        if (!isValidTodo(newTodo)) {
            throw new Error('Invalid todo');
        }
        setTodos([...todos, newTodo]);
    };

    const removeTodo = (id: string) => {
        setTodos(todos.filter((todo) => todo.id !== id));
    };
    return (
        <ServerSideProps key="todos-props" add={addTodo} remove={removeTodo}>
            {todos.map((todo) => (
                <Todo {...todo} />
            ))}
        </ServerSideProps>
    );
};

const isValidTodo = (todo): todo is TodoObject => {
    return todo.id && todo.title && 'completed' in todo;
};

In this example, both Todos and Todo are React Server components, responsible for managing and rendering their respective states on the server-side. The Todos component maintains a list of Todo items, each comprising a unique ID, title, and completion status.

The state of the Todos component is efficiently managed using React Server's useState with a Scopes.Client scope. This ensures that each connected client possesses its own isolated list of todos and individual todo items' states. Consequently, users can interact with the app independently, without any interference with others' data.

On the other hand, the Todo component represents an individual todo item and autonomously manages its state, including the completion status. Similarly, it employs React Server's useState with Scopes.Client scope to handle its state. Leveraging server-side state management allows these components to seamlessly update and synchronize their states with clients. As a result, the UI remains consistently up-to-date and responsive to changes without the need for manual data fetching or polling mechanisms.

Now, let's delve into the frontend implementation.

frontend/src/components/TodoApp.tsx

import {
  Box,
  Button,
  Card,
  CardHeader,
  Checkbox,
  IconButton,
  List,
  ListItem,
  ListItemIcon,
  ListItemSecondaryAction,
  ListItemText,
  TextField,
} from '@mui/material';
import EditIcon from '@mui/icons-material/Edit';
import RemoveCircleIcon from '@mui/icons-material/RemoveCircle';
import { useComponent } from '@state-less/react-client';
import { useEffect, useState } from 'react';

export const TodoApp = (props) => {
  const [component, { loading }] = useComponent('todos', {});
  const [title, setTitle] = useState('');
  const [edit, setEdit] = useState(false);

  if (loading) {
    return null;
  }
  
  return (
    <Card>
      <CardHeader
        title={
          <Box sx={{ display: 'flex', alignItems: 'center' }}>
            <TextField
              value={title}
              label="Title"
              onChange={(e) => setTitle(e.target.value)}
            />
            <Button
              onClick={() => {
                setTitle('');
                component.props.add({ title, completed: false });
              }}
            >
              Add
            </Button>
          </Box>
        }
        action={
          <IconButton onClick={() => setEdit(!edit)}>
            <EditIcon />
          </IconButton>
        }
      ></CardHeader>
      <List>
        {component?.children.map((todo, i) => (
          <TodoItem
            key={i}
            todo={todo.key}
            edit={edit}
            remove={component?.props?.remove}
          />
        ))}
      </List>
    </Card>
  );
};

const TodoItem = (props) => {
  const { todo, edit, remove } = props;
  const [component, { loading }] = useComponent(todo, {});

  if (loading) return null;

  return (
    <ListItem>
      {edit && (
        <ListItemIcon>
          <IconButton onClick={() => remove(component.props.id)}>
            <RemoveCircleIcon />
          </IconButton>
        </ListItemIcon>
      )}
      <ListItemText primary={component.props.title} />
      <ListItemSecondaryAction>
        <Checkbox
          checked={component?.props.completed}
          onClick={() => {
            console.log('TODO', todo);
            component?.props.toggle();
          }}
        />
      </ListItemSecondaryAction>
    </ListItem>
  );
};

The TodoApp component in the frontend code leverages React Server components to seamlessly manage and present a list of todos. It orchestrates the rendering of a form for adding new todos alongside a display of existing todos. Within this structure, the TodoItem component assumes responsibility for rendering individual todo items. It empowers users to toggle their completion status and, when in edit mode, remove the todo items from the list. To facilitate this functionality, both components harness the useComponent hook, which grants access to and facilitates interaction with the state and features offered by the corresponding backend components.

Although the frontend code may appear lengthy, its verbosity is primarily attributed to the integration of material ui, which enhances the visual appeal of the application. Don't let its size deter you; the comprehensive styling enriches the user experience while maintaining the simplicity and effectiveness of the application's core functionality.