# React Server Components Demo: Running the React Notes Reference App

> React Server Components Demo is a reference note-taking application published by the React team to illustrate how Server Components work. The README explicitly marks the feature as experimental and not ready for adoption, and directs developers to use this demo to understand the architecture before it stabilises in frameworks like Next.js.

**reactjs/server-components-demo** — Demo app of React Server Components.

- Repository: https://github.com/reactjs/server-components-demo
- Website: https://reactjs.org/server-components
- Stars: 4,351 · Forks: 639
- Language: JavaScript
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/reactjs-server-components-demo

## What the Demo Is and Why It Exists

The React Server Components Demo is an official reference application from the React team, published alongside a talk introducing Server Components. The README explicitly states that watching the talk before exploring the code is strongly recommended, as it includes a walkthrough of the demo code and highlights how Server Components work.

The demo exists to give developers a concrete running example of an experimental feature. The README describes its purpose as showing the parts of Server Components that are ready for experimentation, while being clear that it is not intended to reflect the performance characteristics or integration patterns of a future stable release.

The application is called React Notes. It is a note-taking app with a sidebar listing notes, a search bar, and an editing panel. It demonstrates Server Components in the context of a recognisable CRUD interface rather than a toy counter or hello-world example.

## What React Server Components Are and What They Are Not

The README draws a precise distinction that prevents a common misunderstanding. React Server Components are a separate technology from Server-Side Rendering (SSR). Server Components let you run specific components purely on the server, keeping their code and data fetching out of the client JavaScript bundle. SSR, by contrast, generates HTML before any JavaScript loads.

This demo shows only Server Components and not SSR. Because it lacks SSR, the README warns that initial page load in this demo has a client-server network waterfall and will be much slower than any SSR framework. Server Components are designed to be used together with SSR, but combining them is out of scope for this demo.

A Server Component runs on the server and sends a rendered result to the client. It can access server-side data sources directly without adding an API endpoint. A Client Component, marked with use client, runs in the browser and can use React state and effects. The architecture of React Notes shows how both types coexist in the same application.

## Setting Up the Demo Locally

The demo requires Node 18 LTS. If you use nvm, run `nvm i` before installing dependencies to match the version specified in .nvmrc. Install dependencies with:

```
npm install --legacy-peer-deps
```

The --legacy-peer-deps flag is required because the demo pins a pre-release React version (18.3.0-next-1308e49a6-20230330) that may conflict with peer dependency expectations of other packages. Start the development server with:

```
npm start
```

This runs the Express server and the Webpack bundler concurrently using the concurrently package. The application is available at http://localhost:4000. The app will not work until the database is set up, as described in the README.

Alternatively, the README describes Docker Compose as an optional setup path. Running `docker-compose up` starts both the Postgres container and the app container. After the containers are running, seed the database with `docker-compose exec notes-app npm run seed`.

## Database Setup: PostgreSQL and the Notes Schema

The demo requires PostgreSQL. The README lists the full setup sequence for a UNIX-like platform. First, create the database and role:

```
psql postgres

CREATE DATABASE notesapi;
CREATE ROLE notesadmin WITH LOGIN PASSWORD 'password';
ALTER ROLE notesadmin WITH SUPERUSER;
ALTER DATABASE notesapi OWNER TO notesadmin;
\q
```

Then connect and create the notes table:

```
psql -d postgres -U notesadmin;

\c notesapi

DROP TABLE IF EXISTS notes;
CREATE TABLE notes (
  id SERIAL PRIMARY KEY,
  created_at TIMESTAMP NOT NULL,
  updated_at TIMESTAMP NOT NULL,
  title TEXT,
  body TEXT
);

\q
```

Finally, populate the database with sample data:

```
npm run seed
```

The README links to two community forks that reduce this setup work. A fork by pomber removes the database requirement entirely (though SQL queries will not work). A fork by prisma uses SQLite via Prisma, requiring no separate database installation.

## The Demo Architecture: Express, Webpack, and React Notes

The README describes three major parts. A Webpack plugin, not defined in the demo repository itself, allows only client components to be included in build artifacts. The plugin handles the split between server and client code at the bundle level.

An Express server serves two things: the API endpoints used in the app, and a special format that renders Server Components on the server. The client reads this format to reconstruct the component tree.

A React application containing both Server Components and Client Components builds the React Notes UI. The package.json shows the React version as a pre-release build from 2023-03-30: react@18.3.0-next-1308e49a6-20230330. This pre-release is pinned deliberately because stable React at the time of the demo's last update did not include Server Components.

The README is explicit that the demo builds on a Webpack plugin setup, and this is not how Server Components will work when stable. The intended production integration path is through a framework such as Next.js that handles the bundler integration internally.

## Three Things the Demo Explicitly Does Not Show

The README dedicates a section to benchmarking warnings that are also limitations to understand. The demo has no server rendering. Because Server Components and SSR are complementary but separate, the demo shows only Server Components, and the resulting initial load is slower than any SSR framework.

The demo has no efficient bundling strategy. The Webpack plugin splits the client JavaScript bundle, but the README notes the split is not necessarily optimal and investigation into better strategies is ongoing.

The demo has no partial refetching. When a user clicks a different note in the sidebar, the entire app shell is refetched from the server. The README identifies partial refetching as an open area of research with no documented solution at the time of the demo's last revision.

These are not incidental omissions. They represent the parts of the Server Components specification that were still being designed when the demo was published.

## How This Demo Relates to Next.js

The README states that Server Components are intended to be used in a framework that supports server rendering, naming Next.js as the example. The demo builds Server Components on top of a Webpack plugin directly, which the README explicitly describes as not the intended production approach.

Next.js is a widely used React framework that handles server rendering, routing, and bundling. The App Router in Next.js supports React Server Components as a first-class feature, managing the bundler integration that this demo does manually. For developers who want to use Server Components in a real application, Next.js provides the integration layer that the demo does not.

This demo's value is educational. It shows the underlying mechanism: the special serialisation format the Express server produces, how client and server components coexist in the component tree, and how the client reads the server output to reconcile component state. Next.js abstracts all of that, but understanding it helps developers debug production applications.

## Maintenance Status and Licence

The last push to the repository was on 2026-03-29. The repository is not archived. The README notes it was updated in March 2023 to match the latest conventions. The React version pinned in package.json is a pre-release build from 2023-03-30. The licence is MIT.

There are no GitHub releases. The demo is a reference implementation, not a versioned library. The credentials.js file visible in the repository's top-level entries holds the database connection configuration for development use.

The repository was built by the React team at Meta and contributors listed in the README. It is available at reactjs.org/server-components for the companion talk.

## Conclusion

Frontend developers and framework authors who want to understand how React Server Components are designed to work will find this demo the clearest reference point the React team has published. The code shows the Webpack plugin integration, the Express server layer, and the split between server-only and client components in a working app. The demo is not a template for production use: the README states it uses patterns that will not reflect the stable implementation, which is expected to land through frameworks like Next.js. Engineers who want to use Server Components today should use a framework that supports them rather than building on this demo's Webpack setup.

## FAQ

### What are React Server Components?

React Server Components let you run specific components purely on the server. The README describes them as separate from but complementary to SSR: SSR generates HTML before JavaScript loads, while Server Components let you run component logic on the server and send the result to the client without including that component's code in the client bundle.

### Is the React Server Components demo ready for production use?

No. The README explicitly states that Server Components are an experimental feature not ready for adoption, and warns users to use the demo at their own risk. It also notes the demo builds on integration patterns that will not reflect the stable implementation.

### What database does the React Server Components demo use?

The demo uses PostgreSQL. The README provides the full setup sequence including creating the notesapi database, the notesadmin role, the notes table, and populating it with npm run seed. A Docker Compose setup is also available as an optional alternative.

## Sources

- [Issues](https://github.com/reactjs/server-components-demo/issues)
- [License: MIT](https://github.com/reactjs/server-components-demo/blob/main/LICENSE)
- [Project website](https://reactjs.org/server-components)
- [reactjs/server-components-demo on GitHub](https://github.com/reactjs/server-components-demo)
- [README](https://github.com/reactjs/server-components-demo/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/reactjs-server-components-demo