DocsPluginsShowcaseReleases
npmStar us on GitHub

Getting Started

IntroductionInstallationProject StructureLayouts and PagesLinking and Navigating

Routing

Folder-Based RoutingFile-Based RoutingDynamic RoutesParallel RoutesIntercepting RoutesCatch-All RoutesMDX & Markdown Pages

Special Files

Loading UIError BoundariesTemplateDefaultNot Found

Data Fetching

LoadersActionsAccessing Route Data

Metadata

Metadata & SEOOpen Graph & TwitterIcons & Favicons

API Routes

API Routes OverviewPlain Function HandlersHono IntegrationDynamic API Routes

Environment Variables

OverviewPrefixes & Client ExposureUsing in API Routes

Styling

CSS OverviewTailwind CSSCSS Modules

Platforms

WebWindowsmacOSLinuxAndroidiOS

Deployment

Deployment OverviewProduction ServerStatic ExportHosting Providers

A native React framework for building cross-platform applications from a single codebase.

Resources

  • Documentation
  • Plugins
  • Showcase
  • Releases

Community

  • GitHub Discussions
  • Reddit
  • Discord
  • LinkedIn

More

  • npm
  • GitHub
  • Issues
  • License

© 2026 Bini Cooperation.

Web

Build web applications with Bini.js - the default platform target.

Web Overview

Web is the default platform target in Bini.js. It is a standard Vite + React app with file-based routing, full static pre-rendering, and a Hono API layer. Your application runs in the browser and can be deployed to any hosting platform.

SSG + Hydration

Pre-rendered static HTML with zero-JS-lag client hydration

Portable API Layer

Hono-powered routes compiled to a single dist/api bundle

Rust-Powered Tooling

Vite + Rolldown, Oxlint, and Oxfmt for instant builds

Web is the default platform on every OS. If you run create-bini-app without a --platform flag, the CLI enters interactive mode with Web pre-selected. To skip the prompt entirely, pass --platform web explicitly.

Requirements

Web apps are pure JavaScript/TypeScript. The only prerequisites are Node.js and Git. The setup is identical on Windows, macOS, and Linux.

  • Node.js 20.19.0 or higher
  • Git - comes with Xcode Command Line Tools on macOS, sudo apt install git on Linux, and winget install --id Git.Git on Windows.

Create Project

Create a new Bini.js project targeting Web and install its dependencies:

>_Terminal
$ npx create-bini-app@latest my-app --platform web
$ cd my-app
$ npm install

If you omit the --platform flag, the CLI drops into an interactive prompt with Web Application pre-selected. It does not silently scaffold a Web project without the flag:

>_Terminal
$ npx create-bini-app@latest
>_Terminal
◆
Platforms?
◼ Web
◻ Desktop (Windows, macOS, Linux)
◻ Android
◻ iOS
↑/↓ to navigate • Space: select • Enter: confirm

Development Server

Start the development server with HMR (Hot Module Replacement). This command is the same on every OS:

>_Terminal
$ npm run dev

The dev server provides:

  • Fast refresh with HMR
  • File-based routing with live updates
  • Server rendering for every HTML navigation
  • API routes served at /api/*
  • Environment variables from .env files
  • Error overlay with bini-overlay

Production Server

Build and serve your application in production mode:

>_Terminal
$ npm run build
$ npm run start

bini-server is a zero-dependency production server that includes:

  • Static file serving with ETag/304 caching
  • API routes from dist/api/index.mjs (compiled during build)
  • Pre-rendered page serving, with dynamic shell fallbacks
  • Graceful shutdown
  • Configurable timeouts and body limits

Pre-rendering & SEO

Every route is pre-rendered to static HTML during npm run build. There is no separate export command or export mode - bini-ssg drives pre-rendering as part of the same Vite build.

SEO Features

Bini.js includes advanced SEO and performance features out of the box:

  • Static Route Discovery: bini-ssg automatically discovers every route from bini-router and pre-renders it to a real HTML file.
  • Link Crawling: Internal <a href> links found in rendered HTML are followed and pre-rendered automatically. There is no depth limit.
  • Metadata Injection: Title tags, descriptions, Open Graph, Twitter cards, canonical URLs, and theme colors are extracted from your export const metadata and injected into the <head> of every page.
  • Head Tag Hoisting: Any <title>, <meta>, or <link> tags rendered by your React components are automatically hoisted into the document <head>.
  • Route-Scoped CSS: Only the CSS used by the specific route is loaded on that page, minimizing render-blocking resources.
  • Lazy-Loaded Routes: Every route is automatically code-split and lazy-loaded by bini-router. No React.lazy() boilerplate is needed.
  • Instant Paint: Browsers paint the static HTML immediately while the client-side JavaScript hydrates in the background, delivering a perfect First Contentful Paint (FCP).

How It Works

npm run build runs vite build. The bini-ssg plugin drives pre-rendering as part of that same build:

  • Static routes (e.g., /, /about) are rendered to real server-rendered HTML.
  • Dynamic routes (e.g., /blog/:slug) get a real HTML page if listed in staticParams, or a shell page for client-side hydration.
  • React 19 renderToPipeableStream is used for server rendering.

Build Command

>_Terminal
$ npm run build

The output is real server-rendered markup. The client then hydrates it with hydrateRoot on load.

Output Structure

Each route gets its own index.html in dist/:

dist
index.html
about
index.html
blog
[slug]
index.html
docs
[...slug]
index.html
assets
index-[hash].js
index-[hash].css
api
index.mjs
404.html
/
/about
/blog/:slug
/docs/*
  • Highlighted files are fully pre-rendered pages for / and /about
  • /blog/:slug and /docs/* are shell pages (unless listed in staticParams)
  • api/index.mjs is the compiled API bundle for bini-server or edge hosts.

Deployment

bini-deploy is bundled into every scaffold and exposed as npm run deploy. For web, it prompts for a hosting target and generates the appropriate configuration and entry files.

Prerequisites

Before deploying, ensure you have a GitHub repository and the required credentials for your chosen hosting provider.

  • A GitHub account and a repository (e.g., https://github.com/you/my-app).
  • For Vercel, Netlify, Cloudflare, or Deno: a free account on that platform.
  • For Node.js hosts (Railway, Render, Fly.io, a VPS): SSH access or a platform account.

Deploy Command

>_Terminal
$ npm run deploy
>_Terminal
◇
Platforms?
◼ Web
◻ Desktop (Windows, macOS, Linux)
◻ Android
◻ iOS
↑/↓ to navigate • Space: select • Enter: confirm
◇
Hosting provider?
● Vercel
○ Netlify
○ Cloudflare
○ Deno Deploy
○ Node.js
↑/↓ to navigate • Enter: confirm
◇
GitHub repository URL?
https://github.com/you/my-app
◇
Branch to push to?
● main (default)
○ + New branch...
◇
Generate deployment files and push to GitHub?
●Yes/○No
◆
Commit message (press Enter for the default):
chore: add deployment configuration

Generated Files

The target you choose determines what bini-deploy creates:

  • Node.js: (none - bini-server reads dist/api/ directly)
  • Netlify: netlify/edge-functions/api.ts + netlify.toml
  • Vercel: api/index.ts + vercel.json
  • Cloudflare: worker.ts + wrangler.toml
  • Deno: server/index.ts

Deployment Options

  • SSG + Node.js API: Build with npm run build (generates static HTML via SSG), serve with npm run start to run the bini-server and handle API routes dynamically (requires Node.js).
  • Fully Static: Build with npm run build, deploy the dist/ folder to any static hosting (Netlify, Vercel, Cloudflare Pages, S3). Note: This serves the pre-rendered pages and client-side hydration, but your API routes will not work unless you use an edge adapter.
  • Edge/Serverless: Use npm run deploy to generate platform-specific entry files for Vercel, Netlify, Cloudflare, or Deno, which serve the static HTML and run your Hono API at the edge.

Node.js Deployment

For Node.js hosts (Railway, Render, Fly.io, a VPS):

>_Terminal
$ npm run build && npm run start

bini-server reads the compiled API bundle from dist/api/index.mjs, so deploy the whole project - not just dist/. Use pm2 on a bare VPS.

GitHub Pages / Subpaths

bini-deploy does not automate GitHub Pages. You must set the subpath manually, build, and upload the static files yourself:

  1. Set base: '/my-repo/' in vite.config.ts.
  2. Run npm run build to generate a subpath-aware dist/ folder.
  3. Upload the dist/ folder to your GitHub Pages branch (e.g., gh-pages) manually or using a tool like gh-pages.
vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { biniroute } from 'bini-router'

export default defineConfig({
  base: '/my-repo/',  // GitHub Pages subpath
  plugins: [react(), biniroute()],
})

Windows

Build a native Windows app with Authenticode signing and NSIS/MSI installers.

macOS

Build a native macOS app with Developer ID signing and notarization.

Linux

Build a native Linux app with AppImage, .deb, and .rpm bundles.

Android

Build a native Android app with keystore signing and Play Store support.

Was this helpful?
PreviousCSS Modules
NextWindows

On this page

  • Web Overview
  • Requirements
  • Create Project
  • Development Server
  • Production Server
  • Pre-rendering & SEO
  • Deployment
Edit this page on GitHub

Web

Build web applications with Bini.js - the default platform target.

Web Overview

Web is the default platform target in Bini.js. It is a standard Vite + React app with file-based routing, full static pre-rendering, and a Hono API layer. Your application runs in the browser and can be deployed to any hosting platform.

SSG + Hydration

Pre-rendered static HTML with zero-JS-lag client hydration

Portable API Layer

Hono-powered routes compiled to a single dist/api bundle

Rust-Powered Tooling

Vite + Rolldown, Oxlint, and Oxfmt for instant builds

Web is the default platform on every OS. If you run create-bini-app without a --platform flag, the CLI enters interactive mode with Web pre-selected. To skip the prompt entirely, pass --platform web explicitly.

Requirements

Web apps are pure JavaScript/TypeScript. The only prerequisites are Node.js and Git. The setup is identical on Windows, macOS, and Linux.

  • Node.js 20.19.0 or higher
  • Git - comes with Xcode Command Line Tools on macOS, sudo apt install git on Linux, and winget install --id Git.Git on Windows.

Create Project

Create a new Bini.js project targeting Web and install its dependencies:

>_Terminal
$ npx create-bini-app@latest my-app --platform web
$ cd my-app
$ npm install

If you omit the --platform flag, the CLI drops into an interactive prompt with Web Application pre-selected. It does not silently scaffold a Web project without the flag:

>_Terminal
$ npx create-bini-app@latest
>_Terminal
◆
Platforms?
◼ Web
◻ Desktop (Windows, macOS, Linux)
◻ Android
◻ iOS
↑/↓ to navigate • Space: select • Enter: confirm

Development Server

Start the development server with HMR (Hot Module Replacement). This command is the same on every OS:

>_Terminal
$ npm run dev

The dev server provides:

  • Fast refresh with HMR
  • File-based routing with live updates
  • Server rendering for every HTML navigation
  • API routes served at /api/*
  • Environment variables from .env files
  • Error overlay with bini-overlay

Production Server

Build and serve your application in production mode:

>_Terminal
$ npm run build
$ npm run start

bini-server is a zero-dependency production server that includes:

  • Static file serving with ETag/304 caching
  • API routes from dist/api/index.mjs (compiled during build)
  • Pre-rendered page serving, with dynamic shell fallbacks
  • Graceful shutdown
  • Configurable timeouts and body limits

Pre-rendering & SEO

Every route is pre-rendered to static HTML during npm run build. There is no separate export command or export mode - bini-ssg drives pre-rendering as part of the same Vite build.

SEO Features

Bini.js includes advanced SEO and performance features out of the box:

  • Static Route Discovery: bini-ssg automatically discovers every route from bini-router and pre-renders it to a real HTML file.
  • Link Crawling: Internal <a href> links found in rendered HTML are followed and pre-rendered automatically. There is no depth limit.
  • Metadata Injection: Title tags, descriptions, Open Graph, Twitter cards, canonical URLs, and theme colors are extracted from your export const metadata and injected into the <head> of every page.
  • Head Tag Hoisting: Any <title>, <meta>, or <link> tags rendered by your React components are automatically hoisted into the document <head>.
  • Route-Scoped CSS: Only the CSS used by the specific route is loaded on that page, minimizing render-blocking resources.
  • Lazy-Loaded Routes: Every route is automatically code-split and lazy-loaded by bini-router. No React.lazy() boilerplate is needed.
  • Instant Paint: Browsers paint the static HTML immediately while the client-side JavaScript hydrates in the background, delivering a perfect First Contentful Paint (FCP).

How It Works

npm run build runs vite build. The bini-ssg plugin drives pre-rendering as part of that same build:

  • Static routes (e.g., /, /about) are rendered to real server-rendered HTML.
  • Dynamic routes (e.g., /blog/:slug) get a real HTML page if listed in staticParams, or a shell page for client-side hydration.
  • React 19 renderToPipeableStream is used for server rendering.

Build Command

>_Terminal
$ npm run build

The output is real server-rendered markup. The client then hydrates it with hydrateRoot on load.

Output Structure

Each route gets its own index.html in dist/:

dist
index.html
about
index.html
blog
[slug]
index.html
docs
[...slug]
index.html
assets
index-[hash].js
index-[hash].css
api
index.mjs
404.html
/
/about
/blog/:slug
/docs/*
  • Highlighted files are fully pre-rendered pages for / and /about
  • /blog/:slug and /docs/* are shell pages (unless listed in staticParams)
  • api/index.mjs is the compiled API bundle for bini-server or edge hosts.

Deployment

bini-deploy is bundled into every scaffold and exposed as npm run deploy. For web, it prompts for a hosting target and generates the appropriate configuration and entry files.

Prerequisites

Before deploying, ensure you have a GitHub repository and the required credentials for your chosen hosting provider.

  • A GitHub account and a repository (e.g., https://github.com/you/my-app).
  • For Vercel, Netlify, Cloudflare, or Deno: a free account on that platform.
  • For Node.js hosts (Railway, Render, Fly.io, a VPS): SSH access or a platform account.

Deploy Command

>_Terminal
$ npm run deploy
>_Terminal
◇
Platforms?
◼ Web
◻ Desktop (Windows, macOS, Linux)
◻ Android
◻ iOS
↑/↓ to navigate • Space: select • Enter: confirm
◇
Hosting provider?
● Vercel
○ Netlify
○ Cloudflare
○ Deno Deploy
○ Node.js
↑/↓ to navigate • Enter: confirm
◇
GitHub repository URL?
https://github.com/you/my-app
◇
Branch to push to?
● main (default)
○ + New branch...
◇
Generate deployment files and push to GitHub?
●Yes/○No
◆
Commit message (press Enter for the default):
chore: add deployment configuration

Generated Files

The target you choose determines what bini-deploy creates:

  • Node.js: (none - bini-server reads dist/api/ directly)
  • Netlify: netlify/edge-functions/api.ts + netlify.toml
  • Vercel: api/index.ts + vercel.json
  • Cloudflare: worker.ts + wrangler.toml
  • Deno: server/index.ts

Deployment Options

  • SSG + Node.js API: Build with npm run build (generates static HTML via SSG), serve with npm run start to run the bini-server and handle API routes dynamically (requires Node.js).
  • Fully Static: Build with npm run build, deploy the dist/ folder to any static hosting (Netlify, Vercel, Cloudflare Pages, S3). Note: This serves the pre-rendered pages and client-side hydration, but your API routes will not work unless you use an edge adapter.
  • Edge/Serverless: Use npm run deploy to generate platform-specific entry files for Vercel, Netlify, Cloudflare, or Deno, which serve the static HTML and run your Hono API at the edge.

Node.js Deployment

For Node.js hosts (Railway, Render, Fly.io, a VPS):

>_Terminal
$ npm run build && npm run start

bini-server reads the compiled API bundle from dist/api/index.mjs, so deploy the whole project - not just dist/. Use pm2 on a bare VPS.

GitHub Pages / Subpaths

bini-deploy does not automate GitHub Pages. You must set the subpath manually, build, and upload the static files yourself:

  1. Set base: '/my-repo/' in vite.config.ts.
  2. Run npm run build to generate a subpath-aware dist/ folder.
  3. Upload the dist/ folder to your GitHub Pages branch (e.g., gh-pages) manually or using a tool like gh-pages.
vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { biniroute } from 'bini-router'

export default defineConfig({
  base: '/my-repo/',  // GitHub Pages subpath
  plugins: [react(), biniroute()],
})

Windows

Build a native Windows app with Authenticode signing and NSIS/MSI installers.

macOS

Build a native macOS app with Developer ID signing and notarization.

Linux

Build a native Linux app with AppImage, .deb, and .rpm bundles.

Android

Build a native Android app with keystore signing and Play Store support.

Was this helpful?
PreviousCSS Modules
NextWindows

On this page

  • Web Overview
  • Requirements
  • Create Project
  • Development Server
  • Production Server
  • Pre-rendering & SEO
  • Deployment
Edit this page on GitHub