One Render Modes

Render Modes

Official docs: Routing, Configuration

One lets you set the render mode globally or per-page. Mix modes freely — a single app can have SSG marketing pages, SSR dashboards, SPA admin panels, and API endpoints.

Quick Reference

Setting the Mode

File suffix (per-page)

app/
  index+ssg.tsx          Static
  dashboard+spa.tsx      Client-only
  feed+ssr.tsx           Server-rendered
  api/data+api.ts        API endpoint

Global default

// vite.config.ts
one({
  web: {
    defaultRenderMode: 'ssg', // pages without a suffix use this
  },
})

Folder suffix (all routes in folder)

app/
  admin+spa/
    _layout.tsx          SPA
    index.tsx             SPA (inherited)
    users.tsx             SPA (inherited)

Layout render mode

app/
  _layout+ssg.tsx        Static shell
  dashboard+spa/
    index.tsx             SPA content

A static layout wrapping SPA pages gives you fast initial paint with client-rendered content.

SSG — Static Site Generation

Default mode. Pages are pre-rendered at build time.

Best for: marketing pages, blogs, docs, landing pages.

// app/index+ssg.tsx (or just index.tsx if SSG is default)
export async function loader() {
  return { posts: await fetchPosts() }
}

export default function Home() {
  const { posts } = useLoader(loader)
  return <PostList posts={posts} />
}

For dynamic SSG routes, export generateStaticParams:

// app/blog/[slug]+ssg.tsx
export async function generateStaticParams() {
  const posts = await getPosts()
  return posts.map(p => ({ slug: p.slug }))
}

export async function loader({ params }) {
  return getPost(params.slug)
}

SSR — Server-Side Rendering

Pages are rendered on the server for every request.

Best for: personalized content, real-time data, pages that need fresh data.

// app/feed+ssr.tsx
import { setResponseHeaders } from 'one'

export async function loader({ request }) {
  const user = await getUser(request)

  setResponseHeaders(headers => {
    headers.set('Cache-Control', 'public, max-age=60')
  })

  return { feed: await getFeed(user.id) }
}

Tip: Always set Cache-Control headers on SSR pages to reduce server load. Use a CDN in front of your server.

SPA — Single Page Application

Pages are rendered entirely on the client. No server-side rendering.

Best for: authenticated dashboards, admin panels, apps where SEO doesn't matter.

// app/admin+spa/index.tsx
export default function Admin() {
  const [data, setData] = useState(null)

  useEffect(() => {
    fetch('/api/admin/stats').then(r => r.json()).then(setData)
  }, [])

  if (!data) return <Loading />
  return <Dashboard data={data} />
}

Pattern: Combine SPA pages with an SSG layout for a fast static shell:

app/
  _layout+ssg.tsx          Static navigation renders instantly
  admin+spa/
    index.tsx              Client-rendered after shell loads

API — HTTP Endpoints

Server-only endpoints that return data, not UI.

// app/api/users+api.ts
export async function GET() {
  return Response.json(await db.users.findMany())
}

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

See the one-api-routes skill for complete API route patterns.

Mixing Modes

A real app typically mixes modes:

app/
  _layout+ssg.tsx              Static shell (nav, footer)
  index+ssg.tsx                Static home page
  blog/
    index+ssg.tsx              Static blog index
    [slug]+ssg.tsx             Static blog posts
  dashboard+spa/
    _layout.tsx                SPA dashboard
    index.tsx                  Client-rendered
    analytics.tsx              Client-rendered
  settings+ssr.tsx             Server-rendered (needs auth)
  api/
    users+api.ts               API endpoint
    webhooks/stripe+api.ts     Webhook handler

Decision Guide