repository·main·Indexed 27 days ago
https://github.com/nitrojs/nitroA production-ready, platform-agnostic server engine designed to extend Vite applications. Nitro provides a zero-config experience for adding server routes and deploying universal JavaScript servers across various environments. Key features include filesystem-based routing, a flexible renderer for SPAs and SSR, and integration with Rolldown for build customization.
Nitro is a production-ready server engine that extends Vite applications. Key capabilities include:
routes/ folder or use a custom entry point (H3, Hono, Elysia, Express).unstorage) that works with filesystem, Redis, Cloudflare KV, and more.plugins/ directory.db0) with support for SQLite, PostgreSQL, MySQL, and Cloudflare D1.The server entry point is responsible for rendering your React application to a streaming HTML response. For edge-compatible streaming, use renderToReadableStream from react-dom/server.edge.
To manage assets (CSS and JS) correctly, import your client and server entries using the ?assets=client and ?assets=ssr query parameters. You can then use the .merge() method on the client assets to combine them with server assets, providing a unified manifest of stylesheets, module preloads, and the main entry script.
import "./styles.css";
import { renderToReadableStream } from "react-dom/server.edge";
import { App } from "./app.tsx";
import clientAssets from "./entry-client?assets=client";
import serverAssets from "./entry-server?assets=ssr";
export default {
async fetch(_req: Request) {
const assets = clientAssets.merge(serverAssets);
return new Response(
await renderToReadableStream(
<html lang="en">
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
{assets.css.map((attr: any) => (
<link key={attr.href} rel="stylesheet" {...attr} />
))}
{assets.js.map((attr: any) => (
<link key={attr.href} type="modulepreload" {...attr} />
))}
<script type="module" src={assets.entry} />
</head>
<body id="app">
<App />
</body>
</html>
),
{ headers: { "Content-Type": "text/html;charset=utf-8" } }
);
},
};To deploy a Nitro application to Cloudflare Pages, use the cloudflare_pages preset.
Note: Cloudflare Workers (cloudflare_module) is currently the recommended preset. Use Pages only if specific features are required.
import { defineConfig } from "nitro";
export default defineConfig({
preset: "cloudflare_pages"
})Nitro automatically generates a _routes.json file for routing. You can override this using the cloudflare.pages.routes config option.
npm run build
wrangler pages devwrangler login
wrangler pages deployUse the following GitHub Actions workflow configuration to build your Nitro app and deploy it to GitHub Pages. This workflow includes a build job that generates the output and a deploy job that uses the actions/deploy-pages action.
Key requirements:
NITRO_PRESET: github_pages in the build step../.output/public directory using actions/upload-pages-artifact@v1.deploy job must have permissions for pages: write and id-token: write.deploy job must depend on the build job via needs: build.name: Deploy to GitHub Pages
on:
workflow_dispatch:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- run: corepack enable
- uses: actions/setup-node@v6
with:
node-version: "18"
- run: npx nypm install
- run: npm run build
env:
NITRO_PRESET: github_pages
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
path: ./.output/public
deploy:
needs: build
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1You can define dynamic routes using the [<param>] syntax. Parameters are accessible via event.context.params or the getRouterParam utility.
[name].ts (e.g., routes/hello/[name].ts matches /hello/nitro).[name]/[age].ts (e.g., routes/hello/[name]/[age].ts). You cannot define multiple params in a single filename.[...name].ts to capture all remaining URL segments (e.g., routes/hello/[...name].ts matches /hello/nitro/is/hot).import { defineHandler } from "nitro";
export default defineHandler((event) => {
const { name } = event.context.params;
return `Hello ${name}!`;
});To deploy a Nitro application to Cleavr, you must set the Nitro preset to cleavr. This allows Nitro to build the application in a format compatible with Cleavr's environment.
Update your configuration file (e.g., nitro.config.ts or your framework's config) to include the cleavr preset:
export default {
nitro: {
preset: 'cleavr'
}
}After pushing your changes to your code repository, follow these steps in the Cleavr dashboard:
Note: Integration with this provider is possible with zero configuration.
.ts (e.g., .get.ts, .post.ts, .put.ts, .delete.ts).To use Express as your backend framework with Nitro, you must provide a custom server entry file named server.node.ts in your project root. Nitro will auto-detect this file and use it as the entry point. This approach gives you full control over Express routing and middleware, but note that the .node.ts suffix indicates this entry is Node.js specific and is not compatible with other runtimes like Cloudflare Workers or Deno.
express and @types/express are installed.nitro() plugin in your vite.config.ts.server.node.ts and export your Express application instance as the default export.import Express from "express";
const app = Express();
app.use("/", (_req, res) => {
res.send("Hello from Express with Nitro!");
});
export default app;To deploy your Nitro application to EdgeOne Pages using the web control panel, follow these steps:
NITRO_PRESET with the value edgeone-pages during the setup process.Global middleware is defined in the middleware/ directory. These handlers run after route rules. You can use event.context to pass data through the lifecycle.
Warning: Returning from a middleware will close the request; avoid doing this unless you intend to terminate the request early.
import { defineHandler } from "nitro";
export default defineHandler((event) => {
event.context.info = { name: "Nitro" };
});To use Nitro's automatic OpenAPI specification generation and interactive documentation UIs, enable the experimental openAPI feature in your nitro.config.ts.
Once enabled, the following endpoints are available during development:
/_openapi.json: The OpenAPI 3.1.0 JSON specification./_scalar: The Scalar API reference UI./_swagger: The Swagger UI.IMPORTANT OpenAPI support is currently experimental.
import { defineConfig } from "nitro";
export default defineConfig({
experimental: {
openAPI: true,
},
});