/seia

:eight_pointed_black_star: Lightweight SSR framework for React Server Components

Primary LanguageTypeScriptMIT LicenseMIT

Seia

React Vite Vite Hono

Lightweight SSR framework for React Server Components

Quickstart • Try demo • Documentation • Wiki • Community

✨ Key Features

  • React Server Components support: Renders ahead of time on the server and streams HTML to the client for improved performance.
  • Unlike Next.js which works only with Webpack-compatible bundlers, Seia adopts Vite for faster development and better compatibility with a great ecosystem.
  • Zero configuration and scaffolding: No more npx create-whatever-app. Start a new project in seconds without any setup or scaffolding required.
  • Minimal client bundle size: Reduces the client bundle size to a minimum at build time, requiring only three files to hydrate on the client.
  • Freedom to choose your tools: Seia does not force you to use specific routing, data fetching, or state management solutions. Use your favorite tools.
  • TypeScript support: Comes with type-safe API and hooks out of the box, but allows you to use JavaScript if you prefer.
  • Deploy anywhere: Deploy your SSR server to Vercel, Netlify, Cloudflare Workers and anywhere Hono supports.

🚀 Quickstart

We provide the create-seia-app wizard to help you get your new project up and running quickly

$ npm create seia-app # yarn create seia-app or pnpm create seia-app

After running the command, it will start to ask you a few questions. Choose the options that best suit your needs. Once you've made your selections, a new project will be created with the specified settings.

Navigate into your newly created project directory and install the dependencies. After that, build your project using the following command:

$ npm run build # yarn build or pnpm build

This will generate a dist folder containing the server and client bundles. To start the SSR server, use:

$ npm start # yarn start or pnpm start

If everything is set up correctly, you should see the server running at http://localhost:5314.

⚡ Migrate from Vite

If you already have a Vite project and want to migrate it to Seia, follow these steps.

First, install Seia as a dependency to your project:

$ npm install seia.js

Important

Seia currently requires react and react-dom as peer dependencies with the exact version 19.0.0-beta-26f2496093-20240514.
Once React 19 has a stable release, Seia will be updated to support the stable version.

After installing Seia, you can optionally add the following commands to your package.json's scripts section for convenience.

"scripts": {
	"build": "seia build",
	"start": "seia start"
}

Then, you can follow the same steps as outlined in the Quickstart Guide to build the project and start the SSR server.

❓ What is Server Components?

React Server Components is a new concept first introduced in React 18 that allows you to render components on the server, but not on the client. What does that mean?

In traditional SSR architectures, the server renders the components and sends the HTML to the client. The client then re-renders the components and hydrates the HTML to make it interactive. This means your components run on both the server and the client, allowing you to access only the intersection of Node.js (or other runtimes) and web browser APIs.

With server components, you don't have to worry about this limitation. You can specify which components should be rendered on the server and which should be rendered on the client. This allows you to access the full Node.js API on the server and the full web browser API on the client, giving you the best of both worlds.

Imagine a simple example like this:

import { readFile } from 'node:fs/promises'

const FileContent = async ({ path }: { path: string }) => {
	const buffer = await readFile(path, 'utf-8')

	return <HtmlEscape>{buffer}</HtmlEscape>
}

We've created a basic file server with React!

The FileContent component reads a file from the file system on the server and returns its content as formatted HTML. We all know that reading server files from a browser is simply not possible! Therefore, the FileContent component should be a server component, ensuring that it will only render on the server.

Then, how do we specify that this component is a server component?

The answer is; we don't have to!

Every components are considered server components by default. If you want to specify that a component should be client component, you can simply write "use client" at the top of the file.

'use client'

import { useState } from 'react'

const Counter = () => {
	const [count, setCount] = useState(0)

	return (
		<div>
			<button onClick={() => setCount(count + 1)}>Increment</button>
			<p>Count: {count}</p>
		</div>
	)
}

🔥 Try Demo

You can try a simple demo of Seia with the Blue Archive Students sample. This project is a simple SSR application that fetches and displays the list of students of the Blue Archive.

👉 Go to sample project README

📖 Documentation

For comprehensive details about the Seia API, configuration, and more, please visit the API documentation.

👥 Join the Community

Become part of the community by joining our official Discord server!

❤️ Support

Your support is invaluable for the ongoing maintenance and improvement of Seia. Here are some ways you can contribute:

  • Spread the word. Share Seia on social media, blogs, or other platforms to help more developers discover it.
  • Give it a star. If you like Seia, please give it a star on GitHub. This helps increase the project's visibility.
  • Report bugs. Seia is still in its early stages, and there may be a lot of bugs or issues that need to be fixed or at least documented. If you find any, please report them as an issue.
  • Suggest improvements. Seia's features are currently quite limited. If you have any ideas or know of similar frameworks with useful features, please share them. I am happy to consider new features.
  • Build with Seia. If you create something using Seia, please let me know. I would love to see your projects.
  • Contribute to Seia. I am glad that you are interested in contributing to Seia. Please see the below roadmap and opened issues to find out how you can help.

📝 Future Roadmap

  • RSC & SSR code splitting.
  • Minimize client bundle.
  • CommonJS modules.
  • Provide configuration options and config file.
  • Vite HMR and fast refresh.
  • Stream RSC payload when navigating pages.
  • Support existing routing solutions, along with RSC.
  • Way to edit header or layout, for example like changing <title>.
  • Streaming and Suspense.
  • Provide CLI.
  • Use user's Vite config and plugins.
  • Distribute Seia as a single Vite plugin, if possible.
  • Context API.
  • Allow importing external React libraries.
  • Server Action?
  • Reduce redundant Vite build call.
  • Rewrite react-server-dom-webpack dependency to pure Vite plugin.
  • Show build-time error when using client-side API without "use client".
  • Add benchmarks.
  • Telemetry.
  • Remove hacks and webpack polyfills.
  • Allow user to use Seia as a hono middleware.

🙋 Where's the name from?

Yurizono Seia(百合ゆり園ぞのセイア), member of the Tea Party at Trinity in the Blue Archive.

❔ What does the default port number 5314 mean?

The port number 5314 is a L33T of "SEIA". This choice is inspired by Vite using port 5173.

🙏 Special Thanks

💖 Sponsors

📜 License

MIT