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.

API Routes Overview

Backend endpoints with plain Request handlers or Hono. Files under app/api/ map to /api/*.

Overview

Place .ts or .js files in src/app/api/ and they become routes at /api/*. Every handler receives a standard Web Request and a context object.

FileRoute
src/app/api/hello.ts/api/hello
src/app/api/users.ts/api/users
src/app/api/posts/index.ts/api/posts
src/app/api/posts/[id].ts/api/posts/:id
src/app/api/[...catch].ts/api/*
Static routes match before dynamic ones, and dynamic ones before catch-alls.

File Structure

The filename becomes the last path segment under /api/. Use index.ts inside a folder for the parent path. API files are marked with the ƒ icon.

app
api
ƒhello.ts
ƒusers.ts
posts
ƒindex.ts
ƒ[id].ts
ƒ[...catch].ts
/api/hello
/api/users
/api/posts
/api/posts/:id
/api/*
Files and folders starting with _ or . are ignored.

Handler Styles

Three handler styles are supported. All receive a Web Request and return a Response.

1. Plain function

src/app/api/hello.ts
export default function handler(request: Request) {
  return Response.json({ message: 'Hello' })
}

2. Per-method exports

Export GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS. Other methods receive 405 with an Allow header, and HEAD falls back to GET.

src/app/api/users.ts
export function GET(request: Request, { params }: { params: Record<string, string> }) {
  return Response.json({ users: [] })
}

export async function POST(request: Request) {
  const body = await request.json()
  return Response.json({ created: body }, { status: 201 })
}

3. Hono app

A default export with a .fetch() method - such as a Hono instance - is mounted under /api. Write Hono routes without the /api prefix.

src/app/api/users.ts
import { Hono } from 'hono'

const app = new Hono()

app.get('/users', (c) => c.json({ users: [] }))
app.post('/users', async (c) => {
  const body = await c.req.json()
  return c.json({ created: body }, 201)
})

export default app
If a file exports both method handlers and a default export, method handlers take precedence for the methods they define.

Request Context

Every handler receives a context object with these fields.

FieldTypeDescription
paramsobjectDynamic route params (e.g. { id: "123" })
searchParamsURLSearchParamsQuery string parameters
envanyRuntime env bindings (or process.env on Node)
waitUntil?functionExtends the request lifetime for background work
src/app/api/users/[id].ts
export function GET(
  request: Request,
  { params, searchParams }: { params: { id: string }; searchParams: URLSearchParams }
) {
  const format = searchParams.get('format') ?? 'json'
  return Response.json({ id: params.id, format })
}

Dynamic Routes

[id] folders or files create dynamic segments. [...catch] matches the remaining segments. Catch-all values are available under params['*'] and under the folder name.

src/app/api/posts/[...slug].ts
export function GET(
  request: Request,
  { params }: { params: { '*': string; slug?: string } }
) {
  const path = params['*']
  return Response.json({ path, segments: path.split('/') })
}

Environment Variables

Access environment variables directly from the env object in the request context. This ensures your code works across all deployment platforms.

src/app/api/email.ts
export function POST(request: Request, { env }: { env: Record<string, string | undefined> }) {
  const smtpHost = env.SMTP_HOST
  const smtpPort = parseInt(env.SMTP_PORT ?? '587', 10)
  
  if (!smtpHost) {
    return Response.json({ error: 'Missing SMTP_HOST' }, { status: 500 })
  }

  return Response.json({ host: smtpHost, port: smtpPort })
}
On Node, env is backed by process.env. On edge platforms, it reads the runtime bindings.

CORS

CORS is off by default. Enable it at the router level with an explicit origin allowlist, or handle it per-route with Hono middleware.

vite.config.ts
import { defineConfig } from 'vite'
import { biniroute } from 'bini-router'

export default defineConfig({
  plugins: [
    biniroute({
      cors: {
        origin: ['https://myapp.com', 'https://app.myapp.com'],
        methods: ['GET', 'POST'],
        headers: ['Authorization', 'Content-Type'],
      },
    }),
  ],
})
Use an explicit origin list in production. Setting cors: true allows any origin.

Deployment

API routes work across platforms. The deploy tool generates the platform entry files for non-Node hosts.

>_Terminal
$ npm run deploy
PlatformEntry
Node.jsThe production server reads dist/api/index.mjs directly
Netlifynetlify/functions/api.mjs
Vercelapi/index.ts
Cloudflareworker.ts
Denoserver/index.ts

Plain Function Handlers

Backend endpoints with plain Request/Response handlers.

Hono Integration

Build API routes with the Hono framework.

Dynamic API Routes

Path parameters and catch-all segments.

Environment Variables

Read secrets in your API routes.

Deployment

Deploy to Node, Vercel, Netlify, Cloudflare, or Deno.

Loaders

Fetch data before a route renders.

Was this helpful?
PreviousIcons & Favicons
NextPlain Function Handlers

On this page

  • Overview
  • File Structure
  • Handler Styles
  • Request Context
  • Dynamic Routes
  • Environment Variables
  • CORS
  • Deployment
Edit this page on GitHub

API Routes Overview

Backend endpoints with plain Request handlers or Hono. Files under app/api/ map to /api/*.

Overview

Place .ts or .js files in src/app/api/ and they become routes at /api/*. Every handler receives a standard Web Request and a context object.

FileRoute
src/app/api/hello.ts/api/hello
src/app/api/users.ts/api/users
src/app/api/posts/index.ts/api/posts
src/app/api/posts/[id].ts/api/posts/:id
src/app/api/[...catch].ts/api/*
Static routes match before dynamic ones, and dynamic ones before catch-alls.

File Structure

The filename becomes the last path segment under /api/. Use index.ts inside a folder for the parent path. API files are marked with the ƒ icon.

app
api
ƒhello.ts
ƒusers.ts
posts
ƒindex.ts
ƒ[id].ts
ƒ[...catch].ts
/api/hello
/api/users
/api/posts
/api/posts/:id
/api/*
Files and folders starting with _ or . are ignored.

Handler Styles

Three handler styles are supported. All receive a Web Request and return a Response.

1. Plain function

src/app/api/hello.ts
export default function handler(request: Request) {
  return Response.json({ message: 'Hello' })
}

2. Per-method exports

Export GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS. Other methods receive 405 with an Allow header, and HEAD falls back to GET.

src/app/api/users.ts
export function GET(request: Request, { params }: { params: Record<string, string> }) {
  return Response.json({ users: [] })
}

export async function POST(request: Request) {
  const body = await request.json()
  return Response.json({ created: body }, { status: 201 })
}

3. Hono app

A default export with a .fetch() method - such as a Hono instance - is mounted under /api. Write Hono routes without the /api prefix.

src/app/api/users.ts
import { Hono } from 'hono'

const app = new Hono()

app.get('/users', (c) => c.json({ users: [] }))
app.post('/users', async (c) => {
  const body = await c.req.json()
  return c.json({ created: body }, 201)
})

export default app
If a file exports both method handlers and a default export, method handlers take precedence for the methods they define.

Request Context

Every handler receives a context object with these fields.

FieldTypeDescription
paramsobjectDynamic route params (e.g. { id: "123" })
searchParamsURLSearchParamsQuery string parameters
envanyRuntime env bindings (or process.env on Node)
waitUntil?functionExtends the request lifetime for background work
src/app/api/users/[id].ts
export function GET(
  request: Request,
  { params, searchParams }: { params: { id: string }; searchParams: URLSearchParams }
) {
  const format = searchParams.get('format') ?? 'json'
  return Response.json({ id: params.id, format })
}

Dynamic Routes

[id] folders or files create dynamic segments. [...catch] matches the remaining segments. Catch-all values are available under params['*'] and under the folder name.

src/app/api/posts/[...slug].ts
export function GET(
  request: Request,
  { params }: { params: { '*': string; slug?: string } }
) {
  const path = params['*']
  return Response.json({ path, segments: path.split('/') })
}

Environment Variables

Access environment variables directly from the env object in the request context. This ensures your code works across all deployment platforms.

src/app/api/email.ts
export function POST(request: Request, { env }: { env: Record<string, string | undefined> }) {
  const smtpHost = env.SMTP_HOST
  const smtpPort = parseInt(env.SMTP_PORT ?? '587', 10)
  
  if (!smtpHost) {
    return Response.json({ error: 'Missing SMTP_HOST' }, { status: 500 })
  }

  return Response.json({ host: smtpHost, port: smtpPort })
}
On Node, env is backed by process.env. On edge platforms, it reads the runtime bindings.

CORS

CORS is off by default. Enable it at the router level with an explicit origin allowlist, or handle it per-route with Hono middleware.

vite.config.ts
import { defineConfig } from 'vite'
import { biniroute } from 'bini-router'

export default defineConfig({
  plugins: [
    biniroute({
      cors: {
        origin: ['https://myapp.com', 'https://app.myapp.com'],
        methods: ['GET', 'POST'],
        headers: ['Authorization', 'Content-Type'],
      },
    }),
  ],
})
Use an explicit origin list in production. Setting cors: true allows any origin.

Deployment

API routes work across platforms. The deploy tool generates the platform entry files for non-Node hosts.

>_Terminal
$ npm run deploy
PlatformEntry
Node.jsThe production server reads dist/api/index.mjs directly
Netlifynetlify/functions/api.mjs
Vercelapi/index.ts
Cloudflareworker.ts
Denoserver/index.ts

Plain Function Handlers

Backend endpoints with plain Request/Response handlers.

Hono Integration

Build API routes with the Hono framework.

Dynamic API Routes

Path parameters and catch-all segments.

Environment Variables

Read secrets in your API routes.

Deployment

Deploy to Node, Vercel, Netlify, Cloudflare, or Deno.

Loaders

Fetch data before a route renders.

Was this helpful?
PreviousIcons & Favicons
NextPlain Function Handlers

On this page

  • Overview
  • File Structure
  • Handler Styles
  • Request Context
  • Dynamic Routes
  • Environment Variables
  • CORS
  • Deployment
Edit this page on GitHub