one Documentation

On web, <Tabs> renders headless: only the focused tab's screen, no tab bar. Your site's own navigation is your tab bar.

To build one, place a component as a child of <Tabs> - it replaces the headless default on web and is ignored on native. Use useTabs to get the tab list and the focused tab:

// app/(tabs)/_layout.web.tsx
import { Link, Tabs, useTabs } from 'one'

function WebTabBar() {
  const { screens, focused } = useTabs()

  return (
    <>
      <nav>
        {screens.map((tab) => (
          <Link
            key={tab.name}
            href={tab.href}
            className={tab.isFocused ? 'active' : undefined}
          >
            {tab.options.title}
          </Link>
        ))}
      </nav>
      {focused.element}
    </>
  )
}

export default function Layout() {
  return (
    <Tabs>
      <Tabs.Screen name="explore" options={{ title: 'Explore', href: '/explore' }} />
      <Tabs.Screen name="profile" options={{ title: 'Profile', href: '/profile' }} />
      <WebTabBar />
    </Tabs>
  )
}

See the headless web navigators guide for more, including how native and web can share the same layout file.

Apps Onestack.Dev Data Docs Configuration (`apps/onestack.dev/data/docs/configuration.mdx`) Copy Section

title: Configuration Copy Chapter

One is entirely configured through a Vite plugin:

/* Detailed source-code truncated for AI context efficiency. */

Note that some of this configuration is ultimately stored into environment variables automatically, accessible in your apps and website. For TypeScript support, add /// <reference types="one/env" /> to get typed access to these variables.

alias Copy Chapter

Per-environment module aliases that work during both Vite transforms and rolldown dep pre-bundling. Unlike Vite's resolve.alias, these are applied via resolveId hooks so they're respected by the optimizer.

Specify aliases per environment. More specific environments (client, ssr, ios, android) override the general ones (web, native).

export default {
  plugins: [
    one({
      alias: {
        // applies to client + ssr environments
        web: {
          'react-native-web': '@tamagui/react-native-web-lite',
        },

        // applies to ios + android environments
        native: {
          'some-package': 'some-package-native',
        },

        // overrides web for ssr only
        ssr: {
          'some-package': 'some-package-ssr',
        },
      },
    }),
  ],
}

Replacement values can be bare specifiers — One resolves them internally.

setupFile Copy Chapter

Path to a JS or TS file to import before the rest of your app runs. One controls your root component, but you may want to run some initialization code before anything else.

export default {
  plugins: [
    one({
      // Single file for all environments
      setupFile: './setup.ts',

      // Or different files per environment
      setupFile: {
        client: './setup.client.ts',
        server: './setup.server.ts',
        native: './setup.native.ts',
      },

      // Or with platform-specific native files
      setupFile: {
        client: './setup.client.ts',
        server: './setup.server.ts',
        ios: './setup.ios.ts',
        android: './setup.android.ts',
      },
    }),
  ],
}

native Copy Chapter

The native object allows you to configure your native apps.

Pass false to completely disable native (iOS/Android) support. When disabled, One will not register the ios/android Vite environments, skip the Metro / React Native dev server plugins, and skip the rolldown native bundle pipeline — useful when you want to use One purely as a web framework.

export default {
  plugins: [
    one({
      native: false,
    }),
  ],
}

native.key Copy Section

One will set up your React Native app to run via AppRegistry.registerComponent(app.key).

This setting must match the key you gave the React Native app container you've built.

native.bundler Copy Section

Which bundler serves the native dev bundle. Options are:

• 'vite' (default): Runs Rolldown with OXC transforms and no Babel
• 'metro': Runs Metro, also with no Babel by default

Use Metro when a dependency requires it. You can also set the ONE_METRO_MODE environment variable to override this setting to 'metro' for a single run.

For detailed information including limitations, configuration options, and performance considerations, see the Metro Mode documentation.

Note that native.bundler only affects dev. one build --platform ios and --platform android always produce the native bundle through the Rolldown path.

Default: 'vite'

native.bundlerOptions Copy Section

Options for whichever bundler native.bundler selects. With 'vite':

export default {
  plugins: [
    one({
      native: {
        bundlerOptions: {
          plugins: [myRolldownPlugin()],
          define: {
            __MY_FLAG__: true,
          },
        },
      },
    }),
  ],
}

plugins are Rolldown plugins run on the native bundle in both dev and build. The native bundler is its own Rolldown instance rather than a Vite environment, so plugins in your top-level plugins array don't reach it unless they ship a native form, as @tamagui/vite-plugin does for its compiler. Those run on native automatically. This option is how you add any other plugin, and a plugin listed here takes the place of a top-level one with the same name.

define follows Vite's rules: a string value is inserted as a raw expression, anything else is JSON stringified. It's deliberately separate from your Vite define rather than inherited from it, because plugins add web-only defines there. @tamagui/vite-plugin sets _WORKLET: false for Reanimated on web, and inheriting that on native would statically kill every worklet.

With 'metro', see the Metro Mode documentation for nativeTransformModules, nativeTransforms, startup, and the Metro config passthroughs.

Imported functions in worklets

For Rolldown, workletImportsPlugin from vxrn makes selected exports from a pure JavaScript package callable inside ordinary worklets:

import { one } from 'one/vite'
import { workletImportsPlugin } from 'vxrn'

export default {
  plugins: [
    one({
      native: {
        bundler: 'vite',
        bundlerOptions: {
          plugins: [workletImportsPlugin({ remend: ['default'] })],
        },
      },
    }),
  ],
}

Keep your usual import remend from 'remend' in application code. The plugin bundles the selected exports and their dependencies into worklets, so they can run on a separate worklet runtime. This is an explicit opt-in that adds bundled code and serialized worklet code for each configured entry.

Select synchronous functions that work without a receiver or native runtime dependencies. The replacement module exposes only the selected exports. Function identity, name, length, attached properties, and constructor behavior are not preserved. Each entry owns its dependency graph, so module state is not shared with other configured entries or ordinary imports through another path.

Initialization happens lazily once per runtime and live module version. Editing a dependency rebuilds the worklet module during development; retained worklets keep their original version. Restart the dev server after changing the plugin configuration or package export mappings.

Node built-ins, React Native runtime packages, dynamic imports, and unsupported free runtime globals are rejected. The plugin cannot prove that a function is pure: the selected functions and their dependencies must not rely on host objects, runtime-specific properties on globalThis, or asynchronous module initialization.

native.app Copy Section

Typed native app manifest. name is the native target and AppRegistry key. one prebuild requires name with ios.bundleId and android.applicationId configured.

export default {
  plugins: [
    one({
      native: {
        app: {
          name: 'OneApp',
          ios: { bundleId: 'com.example.oneapp' },
          android: { applicationId: 'com.example.oneapp' },
        },
      },
    }),
  ],
}

See the iOS Native Guide for the full setup.

native.suspendRoutes Copy Section

Wrap each route screen in a React Suspense boundary on native. On native the JS bundle already contains all route modules, so the boundary only catches the async import() wrapper which resolves on the next microtick. Set this to false to remove the <Suspense fallback={null}> wrapper, which prevents a blank flash when JS-driven navigation animations slide a screen in before the fallback is replaced.

Default: true

native.css Copy Section

Turns on react-native-css-interop support when importing CSS on native. This allows you to use CSS imports in your React Native code.

export default {
  plugins: [
    one({
      native: {
        css: true,
      },
    }),
  ],
}

Default: false

web Copy Chapter

The web object allows you to configure web specific settings.

web.defaultRenderMode Copy Section

Choose between one of ssg, spa or ssr. The default is ssg.

Each mode has trade-offs:

• ssg stands for "Static Site Generated", it is the default mode.

SSG is a great general purpose strategy, where your pages are rendered fully at build-time and turned into static HTML. This means you can get a "perfect" first load, where your app is fully rendered with all content, servable easily by a CDN.

The JS is sent alongside it, and React will hydrate your app and resume running from there. The downside is that you do have some complexity in needing to ensure your pages can render in node, the upside is increased performance and SEO on the web.

• spa stands for "Single Page App", which is the simplest strategy.

SPA mode will not render the page on the server at all, and instead only serve the JavaScript to render your page
to the users browser. This mode avoids some complexity - you don't have to make your React code

• ssr stands for "Sever Side Rendered".

This mode will render your page on the server at the time the browser requests it, running loaders as well for each request.

This mode is likely the least useful, as it means that you must make a full trip to your database at the time of each request, and your client is left waiting for the full render from the server before it can show anything. That said, this mode can be useful if you have dynamically generated content but still want to have the best possible SEO, at the cost of some complexity in supporting server rendering.

redirects Copy Section

You can apply server-level redirects. One serves your app with Hono in production, and so the redirect pattern is simple: your source will be passed to Hono.app.get(source). Any matching path segments that start with : will be replaced into the matching segments in destination. And the redirect will send a response type of 301 if permanent is true, otherwise it will be 302.

web.linkPrefetch Copy Section

Controls link prefetching strategy for improved navigation performance.

export default {
  plugins: [
    one({
      web: {
        // Smart trajectory-based prefetching (default)
        linkPrefetch: 'intent',

        // Or choose a simpler strategy
        linkPrefetch: 'viewport', // prefetch when links enter viewport
        linkPrefetch: 'hover', // prefetch on mouseover only
        linkPrefetch: false, // disable prefetching
      },
    }),
  ],
}

Options:

• 'intent' (default): Uses mouse trajectory prediction to prefetch links before you hover them. Ray-casting detects when you're moving toward a link, with winner-takes-all scoring to avoid over-fetching in dense navigation areas. Falls back to hover for immediate interactions.

• 'viewport': Prefetches links when they enter the viewport (with 100px margin). Good for content-heavy pages with many links.

• 'hover': Traditional hover-based prefetching. Prefetches when you mouseover a link.

• false: Disables link prefetching entirely.

web.deploy Copy Section

Deployment target for production builds. Determines how the server bundle is built.

export default {
  plugins: [
    one({
      web: {
        deploy: 'vercel', // or 'node' or 'cloudflare'
      },
    }),
  ],
}

Options:

• 'node' (default): Standard Node.js server using Hono
• 'vercel': Vercel serverless functions
• 'cloudflare': Cloudflare Workers

web.inlineLayoutCSS Copy Section

When enabled, inlines CSS content directly into the HTML instead of using <link> tags. This eliminates an extra network request for CSS, improving LCP (Largest Contentful Paint) scores.

export default {
  plugins: [
    one({
      web: {
        inlineLayoutCSS: true,
      },
    }),
  ],
}

This inlines ALL CSS. For per-file control, use the .inline.css extension instead, which only inlines the files you mark.

Default: false

Code Splitting Copy Section

One uses Rolldown for production builds and configures sensible code splitting defaults out of the box. By default, chunks smaller than 42KB are merged together to reduce the number of HTTP requests on page load.

You can customize the code splitting behavior through build.rolldownOptions.output.codeSplitting:

export default {
  plugins: [
    one({
      // ... your one() config
    }),
  ],

  build: {
    rolldownOptions: {
      output: {
        codeSplitting: {
          // minimum chunk size in bytes before merging (default: 42000)
          minSize: 42_000,

          // maximum chunk size - splits chunks larger than this
          maxSize: 500_000,

          // group specific modules into named chunks
          groups: [
            {
              name: 'vendor',
              test: /node_modules/,
              priority: 1,
              minSize: 50_000,
              // only create chunk if shared by 2+ entry points
              minShareCount: 2,
            },
          ],
        },
      },
    },
  },
}

Why this matters: Without chunk merging, a large app can produce hundreds of tiny JS files (many under 1KB). Even with HTTP/2 multiplexing, this many requests saturates browser connections and increases total transfer overhead. The 42KB default strikes a balance between granular caching and fewer round-trips.

SPA page optimization: For SPA pages, One skips emitting <link rel="modulepreload"> hints in the HTML since the JS module graph handles its own lazy loading and route preloading happens on hover intent. This avoids saturating the connection with hundreds of preload hints that provide no benefit for client-rendered pages.

web.experimental_scriptLoading Copy Section

Controls how scripts are loaded for improved performance. This is an experimental feature that can significantly improve Lighthouse scores by deferring non-critical JavaScript.

export default {
  plugins: [
    one({
      web: {
        experimental_scriptLoading: 'after-lcp',
      },
    }),
  ],
}

Options:

• 'defer-non-critical': Critical scripts (framework entry, page, layouts) load immediately. Non-critical scripts (component imports, utilities) become modulepreload hints only, reducing network/CPU contention.

• 'after-lcp': Scripts download immediately via modulepreload but execution is deferred until after first paint using double requestAnimationFrame. This allows the browser to paint the SSR content before executing JavaScript. Only applies to SSG pages.

• 'after-lcp-aggressive': Omits initial JavaScript modulepreload hints so images and styles can use the connection first. The deferred bootstrap loads the entry and layout scripts; their imports load the remaining chunks. Best for pages with many chunks or slow networks. Only applies to SSG pages.

Default: undefined (all scripts load with async)

web.sitemap Copy Section

Generate a sitemap.xml file automatically during build. This helps search engines discover and index your pages.

export default {
  plugins: [
    one({
      web: {
        // Simple: just enable it
        sitemap: true,

        // Or configure it
        sitemap: {
          // Base URL for sitemap entries (defaults to ONE_SERVER_URL env var)
          baseUrl: 'https://example.com',

          // Default priority for all routes (0.0 to 1.0)
          priority: 0.7,

          // Default change frequency
          changefreq: 'weekly',

          // Glob patterns for routes to exclude
          exclude: ['/admin/*', '/internal/*'],
        },
      },
    }),
  ],
}

The sitemap automatically:

• Includes all page routes (SSG, SPA, SSR)
• Expands dynamic routes using their generateStaticParams output
• Excludes API routes and not-found pages

Route-level overrides: Routes can export a sitemap object to customize their entry. See Routing Exports for details.

Base URL: If baseUrl isn't specified, One uses the ONE_SERVER_URL environment variable. If neither is set, paths are relative.

web.skewProtection Copy Section

Skew protection detects when deployed assets have changed and handles stale client bundles gracefully instead of showing broken pages.

export default {
  plugins: [
    one({
      web: {
        skewProtection: 'proactive',
      },
    }),
  ],
}

Options:

• true (default): Detects chunk load failures and auto-reloads
• 'proactive': Also polls for new versions and forces full-page navigation when a new deployment is detected
• false: Disable skew protection entirely

See the Skew Protection guide for details.

web.suspendRoutes Copy Section

Wrap each route screen in a React Suspense boundary on web. By default web does not wrap routes in Suspense, to avoid flickers during navigation. Enable this if your routes use React use() or lazy loading and you want Suspense boundaries per route.

Default: false

web.experimentalBundledDev Copy Section

Serve the web client through Vite's bundled dev mode (Rolldown-powered full bundle dev environment) instead of unbundled ESM dev. This means fewer requests and faster parsing, especially for apps with large icon or utility imports. This is dev-only and is ignored for builds.

export default {
  plugins: [
    one({
      web: {
        experimentalBundledDev: true,
      },
    }),
  ],
}

Default: false

react Copy Chapter

react.compiler Copy Section

Enables the new React Compiler for both native and web. Will slow down compilation as it uses Babel, but will improve app performance and reduce the need to write memoization.

export default {
  plugins: [
    one({
      react: {
        compiler: true, // enable for all platforms
        // or
        compiler: 'web', // enable only for web
        // or
        compiler: 'native', // enable only for native
        // or
        compiler: /\/app\//, // enable for files matching regex
        // or
        compiler: (id, env) => {
          // env is 'ios' | 'android' | 'client' | 'ssr'
          return id.includes('/components/')
        },
        // or configure per-platform
        compiler: {
          web: true,
          native: /\/components\//,
        },
      },
    }),
  ],
}

Options:

• true: Enable for all platforms (excluding node_modules, +api files)
• 'web': Enable only for web (client and SSR)
• 'native': Enable only for native (iOS and Android)
• RegExp: Enable for files matching the pattern (full control, no default filtering)
• (id, env) => boolean: Custom function with file path and environment ('ios' | 'android' | 'client' | 'ssr')
• { web, native }: Configure each platform separately with any of the above options

When using RegExp or a function, you have full control over which files are compiled - the default exclusions (node_modules, +api files) are not applied. When using true (or true within the object form), the default filters apply.

Default: false

optimization Copy Chapter

Performance optimization options.

optimization.autoEntriesScanning Copy Section

By default, One scans your file system routes and adds them as Vite entries. This prevents some hard reloads on web as you navigate to new pages, but can slow down startup.

export default {
  plugins: [
    one({
      optimization: {
        autoEntriesScanning: 'flat', // only root-level routes (default)
        // or
        autoEntriesScanning: true, // scan all routes
        // or
        autoEntriesScanning: false, // disable scanning
      },
    }),
  ],
}

Options:

• 'flat' (default): Automatically adds just the routes at the root of your app but nothing nested in non-group folders below that
• true: Scans and adds all routes as entries
• false: Disables auto-scanning entirely

autoWarmPlugin Copy Section

A standalone Vite plugin that passively tracks dependencies Vite discovers during normal development. On your next dev server startup, those deps are pre-included in optimizeDeps.include, eliminating "optimized dependencies changed. reloading" cascades.

Import it from one/vite and add it as a top-level plugin:

import { autoWarmPlugin, one } from 'one/vite'

export default {
  plugins: [
    autoWarmPlugin(),
    one({ ... }),
  ],
}

During the first 5 minutes of each dev session, the plugin polls Vite's in-memory optimizer metadata and caches any newly discovered deps to node_modules/.vite/one-warm-deps.json. This file clears automatically when Vite clears its cache (lockfile or config changes).

To persist the cache permanently (surviving node_modules reinstalls), pass a file path:

autoWarmPlugin('./src/dev/warmDeps.json')

devtools Copy Chapter

Development tools to help debug and understand your app. Enabled by default in development mode.

export default {
  plugins: [
    one({
      // Enable all devtools (default)
      devtools: true,

      // Disable all devtools
      devtools: false,

      // Configure individual tools
      devtools: {
        inspector: true, // enabled by default
        editor: 'cursor', // editor CLI for the inspector, or set LAUNCH_EDITOR
        seoPreview: true, // enabled by default
      },
    }),
  ],
}

devtools.inspector Copy Section

The source inspector lets you quickly find the source code for any element on the page:

1. Hold Option (Mac) or Alt (Windows/Linux) for 0.8 seconds
2. Hover over any element to see its source file location
3. Click to open the file in your editor

This works automatically without any additional setup - One injects the necessary data attributes during development and handles opening files in your configured editor.

devtools.editor Copy Section

Editor CLI command for the source inspector to open files with. Examples: 'cursor', 'code', 'zed', 'subl', 'webstorm'. You can also set it with the LAUNCH_EDITOR or EDITOR environment variable.

export default {
  plugins: [
    one({
      devtools: {
        editor: 'cursor',
      },
    }),
  ],
}

devtools.seoPreview Copy Section

The SEO Preview panel helps you visualize how your pages will appear in search results and social media shares:

1. Press Alt+S to toggle the panel
2. View previews for:
   • Google Search - How your page appears in search results
   • Open Graph - How your page appears when shared on Facebook, LinkedIn, etc.
   • Twitter Card - How your page appears when shared on Twitter/X
3. See all meta tags at a glance with validation warnings for common SEO issues

The panel automatically updates as you navigate or modify meta tags, making it easy to verify your SEO configuration during development.

devtools.plugins Copy Section

Browser plugin modules to load into the One devtools overlay. Each entry is a module specifier or a path relative to the project root. The module default exports a OneDevtoolsPlugin, created with defineDevtoolsPlugin from one/devtools.

export default {
  plugins: [
    one({
      devtools: {
        plugins: ['./devtools/runtime-inspector.ts'],
      },
    }),
  ],
}

See Dev Tools for the plugin shape.

devtools.rozenite Copy Section

React Native DevTools plugins hosted through Rozenite. One discovers installed Rozenite packages from your dependencies and serves their panels on the native dev server, so j and dt show them without a Metro wrapper.

export default {
  plugins: [
    one({
      devtools: {
        rozenite: {
          include: ['@rozenite/storage-plugin'],
          exclude: ['@rozenite/network-activity-plugin'],
          pluginDisplay: 'sidebar', // or 'tabs'
        },
      },
    }),
  ],
}

Set rozenite: false to keep the stock React Native DevTools frontend. When no plugin is installed, One does not mount the Rozenite host.

devtools.routeDebug Copy Section

The Route Debug panel helps you understand your current route state during development:

1. Press Alt+R to toggle the panel
2. View information about the current route:
   • Pathname - The current URL path
   • Segments - Breadcrumb-style view of path segments
   • Route Params - Dynamic route parameters (e.g., [slug], [id])
   • Search Params - Query string parameters
   • Hash - URL fragment (if present)
   • Full URL - Complete URL for reference

The panel updates automatically as you navigate, making it easy to debug routing issues and verify params are being parsed correctly.

devtools.loaderTiming Copy Section

The Loader Timing Waterfall panel shows performance metrics for your route loaders:

1. Press Alt+L to toggle the panel
2. View timing data for each loader:
   • Module Load Time (blue) - Time to download and parse the loader module
   • Execution Time (green) - Time for the loader function to complete
   • Total Time - End-to-end timing
   • Source - Whether this was an initial load, refetch, or preload
3. Visual waterfall shows relative timing of module load vs execution
4. Error states are highlighted with red indicators

The panel helps identify slow loaders and understand where time is being spent - whether in module loading (suggesting code splitting issues) or execution (suggesting slow data fetching).

devtools.routePreload Copy Section

The Route Preload panel shows which routes have been preloaded during navigation:

1. Press Alt+P to toggle the panel
2. View preloaded routes with status:
   • Loading - Preload in progress
   • Loaded - Successfully preloaded (shows duration, loader/CSS status)
   • Error - Preload failed (shows error message)

Note: Route preloading only works in production builds. In development, the panel shows a notice explaining this. Run yarn build && yarn serve to test preloading behavior.

Preloading is automatically triggered when users hover over links, warming the cache for likely navigation targets.

devtools.errorPanel Copy Section

The Error Panel shows errors caught by error boundaries and loaders during development:

1. Press Alt+E to toggle the panel
2. View error history with:
   • Error Type - Whether from render, loader, or hydration
   • Route - The route where the error occurred
   • Error Message - The error message with expandable stack trace
   • Timestamp - When the error occurred

The panel automatically appears when the first error is caught, making it easy to spot issues immediately. Click "Clear" to reset the error history. Error boundaries and loaders dispatch events that the panel listens to, giving you a unified view of all errors in your app.

patches Copy Chapter

While building One we found ourselves needing to apply small patches to a variety of packages. Packages in the React Native ecosystem are often published only for Metro, and so have a variety of weird setups.

We built an internal Vite plugin to easily apply patches across any package manager, but after installing One into a few larger production projects, we found ourselves wanting to have access to it.

The patches option lets you coerce your node_modules to be compatible with Vite.

Here's an example:

import type { UserConfig } from 'vite'
import { one } from 'one/vite'

export default {
  plugins: [
    one({
      patches: {
        // passing an object lets you easily apply patches to your actual node_modules
        '@sentry/react-native': {
          // you can specify a semver range to only apply to certain versions:
          version: '~15.2.0',

          // you can use globs to apply to only specific files
          // if you pass an array value, One applies those transforms to matching files:
          //    swc => @swc/core will transform your file into CommonJS compatible code, removing JSX as well
          //    flow => the FlowType transformer will run to remove Flow types
          //    jsx => transforms JSX only
          '**/*.js': ['flow', 'swc'],

          // you can also apply custom transforms using a function
          'dist/js/utils/environment.js': (contents) => {
            if (typeof contents !== 'string') return
            return contents.replace(
              `import { version as RNV } from 'react-native/Libraries/Core/ReactNativeVersion';`,
              `import { Platform } from 'react-native';\nconst RNV = Platform.constants.reactNativeVersion;\n`
            )
          },
        },
      },
    })
  ]
} satisfies UserConfig

Any transforms that are applied to specific files in node_modules will only be applied once. The original files will be stored alongside the transformed ones.

router Copy Chapter

The router object allows you to configure routing behavior.

router.root Copy Section

Dangerously customize the router root directory. This may lead to unexpected behavior. Prefer the default app directory, or pass --appDir to one generate-routes when your routes live elsewhere.

router.ignoredRouteFiles Copy Section

An array of globs that One uses to ignore files in your routes directory. If a file matches any pattern, it will not be treated as a route.

This is particularly useful for ignoring test files, stories, or other files you want to colocate with your routes but don't want to be treated as actual routes.

export default {
  plugins: [
    one({
      router: {
        ignoredRouteFiles: [
          '**/*.test.*',
          '**/*.spec.*',
          '**/*.stories.*',
          '**/*.utilities.*',
        ],
      },
    }),
  ],
}

Limitations: Currently, we only support patterns starting with **/*.

router.experimental.typedRoutesGeneration Copy Section

Auto-generate route type helpers in your route files. Route types are always generated in app/routes.d.ts, but this option controls whether One automatically inserts type helpers into your route files.

export default {
  plugins: [
    one({
      router: {
        experimental: {
          typedRoutesGeneration: 'runtime', // or 'type' or false
        },
      },
    }),
  ],
}

Options:

• false (default): No auto-generation, manually add types yourself
• 'type': Auto-inserts type-only helpers:

import type { RouteType } from 'one'
type Route = RouteType<'/your/[route]'>

• 'runtime': Auto-inserts runtime helpers:

import { createRoute } from 'one'
const route = createRoute<'/your/[route]'>()

The insertion happens automatically when route files are created or modified, with proper spacing and without modifying your existing code.

For more information, see the Typed Routes documentation.

build Copy Chapter

Build-time options. See one build for the full build documentation.

build.concurrency Copy Section

Maximum number of static pages to build concurrently. The default of two keeps peak memory low; raise it on a machine with memory to spare. ONE_BUILD_CONCURRENCY overrides this value.

export default {
  plugins: [
    one({
      build: {
        concurrency: 4,
      },
    }),
  ],
}

Default: the smaller of your CPU core count and 2

build.workers Copy Section

Use worker threads for parallel static page generation during build. This utilizes multiple CPU cores for faster builds. Set to false to disable, or use ONE_BUILD_WORKERS=0 for a single run (=1 forces them on).

Default: true

build.server / build.api Copy Section

build.server accepts VXRN server build options, or false. build.api accepts VXRN build options for API routes.

build.securityScan Copy Section

Scan client bundles for leaked secrets (API keys, tokens, passwords) after building. This catches accidental exposure of server-side secrets in client-facing JavaScript before they reach production.

export default {
  plugins: [
    one({
      build: {
        // Log warnings when secrets are found (default)
        securityScan: 'warn',

        // Fail the build if secrets are found (recommended for production)
        securityScan: 'error',

        // Disable scanning entirely
        securityScan: false,

        // Object form for fine-grained control
        securityScan: {
          level: 'error',
          safePatterns: [
            // exact strings that are known safe
            '09259e3b-7be8-46f6-9801-106bf1866e1c',
            // regex patterns for domain-specific matches
            /my-app-test-token-[a-z]+/,
          ],
        },
      },
    }),
  ],
}

Options:

• 'warn' (default): Log warnings but don't fail the build
• 'error': Fail the build if secrets are detected — recommended for production CI/CD
• false: Disable scanning entirely
• { level, safePatterns }: Object form with level ('warn' or 'error') and safePatterns (array of strings or RegExp to ignore)

The scanner checks for common secret patterns including Anthropic, OpenAI, Stripe, GitHub, and AWS keys, as well as generic secret/password/token assignments. Known safe patterns (WebRTC constants, CSS tokens) are automatically excluded. Use safePatterns to add your own.

server Copy Chapter

Production server options, passed through to the underlying server. See one serve for the CLI side.

server.loggingEnabled Copy Section

Log HTTP requests to the console.

Default: true

skipEnv Copy Chapter

Skip loading .env files during build. The same effect for a single run comes from the one build --skip-env flag, which takes precedence when passed.

export default {
  plugins: [
    one({
      skipEnv: true,
    }),
  ],
}

ssr Copy Chapter

Server-side rendering configuration.

ssr.autoDepsOptimization Copy Section

One scans dependencies on startup and decides which ones to optimize based on known problematic dependencies. These include react-native and react, which need to be optimized to work. It finds all parent dependencies of the known bad deps and adds them to ssr.optimizeDeps.include.

export default {
  plugins: [
    one({
      ssr: {
        // Enable with default include pattern (default)
        autoDepsOptimization: true,

        // Disable entirely
        autoDepsOptimization: false,

        // Configure include/exclude patterns
        autoDepsOptimization: {
          include: /node_modules/,
          exclude: /some-package/,
        },
      },
    }),
  ],
}

Note: The full path (e.g., <your_project_path>/node_modules/<some_package>) is used to match dependencies. If you're using a string to match a package name, you may want to add */ at the start and /* at the end.

Default: { include: /node_modules/ }

ssr.dedupeSymlinkedModules Copy Section

In monorepos with symlinked workspace packages, Vite's SSR optimizer registers pre-bundled deps by their node_modules path, but the resolver follows symlinks to the real source path. This creates duplicate module instances: the optimizer serves one copy while source imports create another.

Enable this to redirect symlink-resolved paths back to node_modules paths so the optimizer can recognize and deduplicate them.

export default {
  plugins: [
    one({
      ssr: {
        dedupeSymlinkedModules: true,
      },
    }),
  ],
}

Default: false

environmentGuards Copy Chapter

Configure environment guard behavior for server-only, client-only, native-only, and web-only imports.

One enforces these guard imports to prevent modules from being used in the wrong build environment. However, some libraries (like floating-ui) import client-only even though the imported code works fine on the server when you're only importing utilities.

export default {
  plugins: [
    one({
      // Disable the client-only guard (allows importing on server)
      environmentGuards: {
        disableGuards: ['client-only'],
      },

      // Or disable all environment guards entirely
      environmentGuards: {
        disabled: true,
      },
    }),
  ],
}

Options:

• disabled: When true, disables all environment guard checks. All guard imports become no-ops regardless of environment.
• disableGuards: An array of specific guard types to disable. Options are 'server-only', 'client-only', 'native-only', and 'web-only'.

Default: All guards are enabled.

transform Copy Chapter

Per-file control over how code transforms. One uses OXC for worklets and React Compiler. Reanimated callbacks, gesture callbacks and explicit worklets do not require a Babel plugin. Babel still runs for configured Babel transforms and syntax that needs it.

Pass a function that receives the file id, its code, and the build context, and returns how to transform it:

export default {
  plugins: [
    one({
      transform: ({ id }) => {
        if (id.includes('node_modules')) return false
        return true
      },
    }),
  ],
}

The function receives { id, code, development, environment, reactForRNVersion }, where environment is 'ios' | 'android' | 'client' | 'ssr'. It returns:

• true: default transforms
• false: no transforms
• 'babel': force the Babel default transform
• 'swc': force the SWC default transform
• 'oxc': force the OXC default transform
• { transform: 'babel', ... }: force Babel with custom options
• { transform: 'swc' | 'oxc', ... }: force SWC or OXC with custom options

Babel defaults to preset @babel/preset-typescript with plugins for destructuring, runtime helpers, JSX, and async functions. SWC targets es5 for native and es2020 for web.

The Environment API Copy Chapter

One runs on Vite 8 and makes use of its Environment API.

This makes it easier to target React Native, as you can specify configuration for iOS, Android and web separately. One defines ios and android environments, respectively. For web, we follow the Vite standard of having a client and ssr environments (for client-side and server-side bundles).

You'll want to lean on using the Environment API to configure as much as you can in your vite.config.ts. It may also mean that some plugins can cause issues by configuring things across all four environments when you really only want it for client-side, or not. We're working on some helpers to make this easier, but in general you can check for this.environment.name in plugin hooks (like transform and load) to conditionally exit early from their logic for environments where you don't want the plugin logic to run.

One assumes the following environments:

• client: Web client-side (matching Vite default)
• ssr: Web server-side (matching Vite default)
• ios: iOS
• android: Android

We set up platform-specific extensions based on the environment:

• client: .web.(js|ts|tsx|mjs)
• ssr: .server.(ts|tsx), .web.(js|ts|tsx|mjs)
• ios: .(ios|native).(js|ts|tsx|mjs)
• android: .(android|native).(js|ts|tsx|mjs)

Server-only files Copy Section

Files with a .server.ts or .server.tsx extension are resolved only in the ssr environment. This lets you colocate server-only code next to shared code:

src/
  db.ts            # shared types/interface
  db.server.ts     # server-only implementation (database queries, secrets, etc.)

When you import './db' from a server-rendered route or loader, it resolves to db.server.ts. On the client or native, it resolves to db.ts.

If a .server.ts file is explicitly imported on the client or native (e.g. import './db.server'), the build will throw an error to prevent server code from leaking into client bundles.

Other Exports Copy Chapter

The one/vite import has a few other exports that may be useful.

`resolvePath` Copy Section

When you are setting an alias in Vite, it wants you to fully specify the import path. We use resolvePath to help with this, it's a bit like require.resolve that works in ESM or CJS. It's also similar to import.meta.resolve, except it returns an absolute path that Vite expects rather than a file path.

Default Configuration Copy Chapter

One sets up some default configuration out of the box, including a variety of plugins and settings that make React Native and the ecosystem of packages that are popular "just work".

Some base configuration we set:

• publicDir to "public"
• clearScreen to false so we can output the quick actions

We set up defines:

• __DEV__ to true in development mode, or false otherwise
• process.env.NODE_ENV

We set up alias based on environment:

• react-native => react-native-web for web environments

We also detect if you have a PostCSS config file (js, ts, or json) and set the css. The internal logic is something like:

{
  css: postCSSConfigPath
    ? {
        postcss: postCSSConfigPath,
      }
    : {
        transformer: 'lightningcss',
        lightningcss: {
          targets: {
            safari: (15 << 16) | (2 << 8),
          },
        },
      }
}

Apps Onestack.Dev Data Docs Dev Tools (`apps/onestack.dev/data/docs/dev-tools.mdx`) Copy Section

title: Dev Tools Copy Chapter

One has two development tool surfaces:

• A browser panel for web apps, with SEO, route, loader, error, and source inspection panels.
• React Native DevTools for iOS and Android apps, where One serves the stock debugger and can host Rozenite plugins.

Both work in development with no setup. You can add your own panels to the web overlay, and Rozenite plugin packages automatically appear in React Native DevTools.

Opening Dev Tools Copy Chapter

For the web overlay, press Alt+Space (Option+Space on Mac) to open the spotlight menu, then select a tool. You can also use keyboard shortcuts to jump directly to a specific panel:

• Alt+S - SEO Preview
• Alt+R - Route Info
• Alt+L - Loader Timing
• Alt+E - Errors

Press Escape to close any panel.

For React Native, press j or dt in the one dev terminal. That opens React Native DevTools for the connected Hermes app, with React DevTools, the JavaScript console, sources, network, and memory panels.

React Native DevTools attaches to one app at a time. If another debugger or a CDP client is attached, close it before opening DevTools again.

SEO Preview Copy Chapter

See how your page appears in Google search results and check for common SEO issues:

• Google Preview - Live preview of your search result appearance
• Meta Tags - View title, description, and Open Graph tags
• Issues - Warnings for missing or too-long meta tags

Route Info Copy Chapter

Debug the current route state:

• Pathname - The current URL path
• Segments - Path broken into segments
• Route Params - Dynamic params from the route (e.g., [id])
• Search Params - Query string values

Loader Timing Copy Chapter

Visualize loader performance with a waterfall breakdown:

• Module Load Time - Time to import the loader module
• Execution Time - Time to run the loader function
• Total Time - Combined timing with visual bar

Useful for identifying slow loaders and optimizing data fetching.

Errors Copy Chapter

Track errors from error boundaries and loaders:

• Error Type - Whether from a boundary or loader
• Timestamp - When the error occurred
• Message - The error message

Errors are collected in real-time so you can see issues as they happen.

Source Inspector Copy Chapter

The inspector is injected automatically in development when devtools.inspector is enabled (the default). It works through the data-one-source attribute One adds to components during development. Hold Option (Mac) or Alt (Windows/Linux) for 0.8 seconds and hover over any element to see its source location highlighted. Click to open a picker showing:

• Quick actions:
  • Open - Open topmost component in your editor
  • Path - Copy all source paths to clipboard
  • Selector - Copy a smart CSS selector (prefers IDs)
  • Record - Start recording user input (see below)
• Parent list - Click any parent component to open that file

Files open in the editor configured via devtools.editor, or the LAUNCH_EDITOR / EDITOR environment variable.

SourceInspector component Copy Section

one also exports a SourceInspector component with its props type, kept for backwards compatibility:

import { SourceInspector } from 'one'

// deprecated: the inspector above is injected automatically.
// this component renders nothing. remove it for cleaner code.
export function Layout() {
  return <SourceInspector />
}

SourceInspectorProps accepts hotkey and enabled, but both are deprecated: the activation key and enabled state now come from the injected devtools script and the devtools.inspector config.

Input Recording Copy Chapter

Record user interactions for bug reports or AI-assisted debugging. Start recording from:

• The Record button in the Source Inspector picker
• Record Input in the Alt+Space spotlight menu

After a 2-second countdown, recording begins. Tap Option to stop and copy the log to clipboard.

The output is a compact, line-based format optimized for AI consumption:

# Recording 2024-03-02T12:30:00.000Z
# https://localhost:3000/dashboard
# components: Button < Card < Dashboard
# selector: [data-testid="submit-btn"]
# window: 1920x1080 scroll:0,0
# duration: 3200ms events: 28

0 click 450,320 btn:0 [#submit] @Button.tsx:15 "Submit"
85 keydown Tab
142 focus [input.email]
200 input val:"test@" [input.email]

# final hover: [.sidebar > nav]
# final source: Nav.tsx:42:5

Events captured include clicks, keyboard input, scroll, focus/blur, input changes, wheel, resize, and more.

Panel Features Copy Chapter

The dev tools panel is:

• Draggable - Drag the header to reposition
• Edge Snapping - Snaps to screen edges with 10px padding
• Resizable - Tracks window resize when snapped to edges

Extending the web panel Copy Chapter

A plugin is a module that default exports a OneDevtoolsPlugin. Use the defineDevtoolsPlugin helper so the editor checks the shape:

// devtools/runtime-inspector.ts
import { defineDevtoolsPlugin } from 'one/devtools'

export default defineDevtoolsPlugin({
  name: 'runtime-inspector',
  title: 'Runtime Inspector',
  category: 'Tuning',
  // An iframe keeps a devtool that already runs its own UI and server as-is.
  panel: {
    url: 'http://localhost:4577',
  },
  actions: [
    {
      id: 'open-web-panel',
      title: 'Open Runtime Inspector',
      run() {
        window.open('http://localhost:4577', '_blank')
      },
    },
  ],
})

Register it in vite.config.ts:

import { one } from 'one/vite'

export default {
  plugins: [
    one({
      devtools: {
        plugins: ['./devtools/runtime-inspector.ts'],
      },
    }),
  ],
}

Plugin modules run in the browser. They can add a panel, actions, or both:

• panel.url loads an existing devtools page in an iframe. Use this for tools that already run their own frontend and server.
• panel.mount(root, context) renders a panel directly into the overlay. Return a cleanup function to remove listeners when the panel closes.
• actions appear in the Alt+Space spotlight and receive the same context as panels.

The context exposes project, url, openPanel, and closePanel. Panel ids are namespaced as plugin:<name>. Two plugins cannot claim the same name.

Plugins are loaded only in development. The module is resolved through Vite, so local TypeScript and JSX files work without a build step.

Rozenite plugins in React Native DevTools Copy Chapter

One hosts the Rozenite plugin convention for React Native. If a Rozenite plugin package is installed in your app, One mounts its plugin host on the native dev server and React Native DevTools shows the panels. Existing Rozenite plugins work without a Metro wrapper or a separate withRozenite config.

bun add -d @rozenite/storage-plugin

On the next one dev, pressing j or dt opens DevTools with the Storage panel. One logs the plugin names it found:

[one] React Native DevTools plugins: @rozenite/storage-plugin (open with dt or j)

Discovery checks direct dependencies for a Rozenite manifest (dist/rozenite.json), the same convention Rozenite's Metro integration uses. To pin the list or exclude a plugin:

one({
  devtools: {
    rozenite: {
      include: ['@rozenite/storage-plugin'],
      exclude: ['@rozenite/network-activity-plugin'],
      pluginDisplay: 'sidebar', // or 'tabs'
    },
  },
})

Set rozenite: false to keep the stock React Native DevTools without the Rozenite host. When no Rozenite plugin is installed, One leaves the debugger frontend untouched.

One hosts Rozenite when One's Vite bundler serves the native app, which is the default. If you set native.bundler: 'metro', keep using Rozenite's own withRozenite Metro wrapper instead.

The device half of a Rozenite plugin still lives in your app. Follow the plugin's install instructions and import it once from your app entry when it asks you to.

Runtime Inspector Copy Section

Runtime Inspector is the reference adapter for this API. It already ships its semantics and layouts as a protocol-first package with a Rozenite panel. In a One app:

1. Add @runtime-inspector/react-native and @runtime-inspector/panel-rozenite to the app.
2. Import the panel once from the app entry: import '@runtime-inspector/panel-rozenite'.
3. Press j or dt. Runtime Inspector appears in React Native DevTools through Rozenite.

Its web panel already runs as its own server, so the web adapter is a plugin with panel: { url } like the example above. No Runtime Inspector protocol change is needed for either host.

Configuration Copy Chapter

Dev tools are enabled by default in development mode. To disable them, set:

// vite.config.ts
import { one } from 'one/vite'

export default {
  plugins: [
    one({
      devtools: false,
    }),
  ],
}

To keep the web tools but change individual features:

one({
  devtools: {
    inspector: true,
    editor: 'cursor',
    seoPreview: true,
    // browser plugin modules for the One overlay
    plugins: ['./devtools/my-panel.ts'],
    // Rozenite host for React Native DevTools
    rozenite: {
      pluginDisplay: 'tabs',
    },
  },
})

Apps Onestack.Dev Data Docs Environment (`apps/onestack.dev/data/docs/environment.mdx`) Copy Section

title: Environment Copy Chapter

Variables Copy Section

Loading .env files and process.env

One handles environment variables for you in a few ways.

First, it handles loading .env files during development and in production. In order to ease compatibility with ESM and CJS, One makes your loaded environment variables (from .env and from process.env) automatically be defined onto both import.meta.env and process.env.

Second, One ensures that all environment variables loaded are only available to the server-side functionality, unless they are prefixed with ONE_PUBLIC_ or VITE_ (Vite convention).

So, for example ONE_PUBLIC_DAYTIME=false one dev would set both process.env.ONE_PUBLIC_DAYTIME and import.meta.env.ONE_PUBLIC_DAYTIME to be the string "false" on both server and client.

ONE_PUBLIC_ is One's naming convention. EXPO_PUBLIC_ is also accepted; see Coming from Expo.

But, SOME_RANDOM_VAR=2 would not be exposed to the client side, because it lacks the appropriate prefix.

Preset environment variables Copy Section

One also sets some environment variables for you, available on both process.env and import.meta.env.

Server

• ONE_PORT sets the port for both one dev and one serve. This is equivalent to passing --port on the command line, but works across both commands and can be set in your .env file or deployment config. If --port is also passed, the CLI flag takes precedence.
• ONE_FORCE_PORT overrides the port for both one dev and one serve, taking precedence over --port and ONE_PORT. Useful for CI or deployment environments where the port must be fixed regardless of other configuration.

Port priority (highest wins):

1. ONE_FORCE_PORT
2. --port CLI flag
3. ONE_PORT
4. Built-in defaults (8081 for dev, 3000 for serve)

Core Variables

• ONE_CACHE_KEY is set to a random number for each production build, or stable per dev server run. Useful for cache keys.
• ONE_APP_NAME is set to your native.app.name setting, falling back to native.key.
• ONE_SERVER_URL is set in development mode to the current running server URL, like http://0.0.0.0:8081. You are expected to set this yourself for production builds.
• ONE_DEFAULT_RENDER_MODE is set to either "ssr", "ssg", or "spa" based on your defaultRenderMode setting.
• ONE_RENDER_MODE is the render mode of the current page being rendered ("ssr", "ssg", or "spa"). Set before the setup file runs so you can conditionally skip setup logic for certain modes.

Platform Detection

• VITE_ENVIRONMENT is set to "client" for client-side web, "ssr" for server-side web, or "ios" / "android" for native platforms.
• VITE_NATIVE is "1" for native platforms (iOS and Android), or "" for web (client and SSR). Uses truthy/falsy strings to avoid polluting process.env types. Useful for tree-shaking native-only code.
• ONE_PLATFORM is "web", "ios", or "android".
• TAMAGUI_TARGET is "web" for web builds or "native" for native builds. Used by Tamagui and One native route branches.

React Native

Available in native builds:

• REACT_NATIVE_VERSION contains the React Native version string.
• REACT_NATIVE_PLATFORM is set to "ios" or "android" in native builds.
• REACT_NATIVE_SERVER_PUBLIC_PORT is the dev server port for React Native.

TypeScript Types Copy Section

One provides TypeScript types for all preset environment variables. To enable them, add a triple-slash reference to your project:

/// <reference types="one/env" />

You can add this to any .d.ts file in your project (such as env.d.ts or vite-env.d.ts), or include it in a file that's part of your TypeScript compilation.

This gives you autocomplete and type checking for import.meta.env.VITE_ENVIRONMENT, process.env.VITE_NATIVE, and all other One environment variables.

Apps Onestack.Dev Data Docs Exports WithLayoutContext (`apps/onestack.dev/data/docs/exports-withLayoutContext.mdx`) Copy Section

title: withLayoutContext Copy Chapter

Today there are a few built-in navigators: Slot, Stack, etc. But you may want to create your own.

A React Navigation navigator can become a One layout through withLayoutContext. For example, an app can wrap a native stack with shared route sorting and protected-route support:

To make any React Navigation navigator work inside a One layout, use withLayoutContext:

import { createNativeStackNavigator } from '@react-navigation/native-stack'
import { withLayoutContext } from 'one'

const ModalNavigator = createNativeStackNavigator().Navigator

export const ModalStack = withLayoutContext(
  ModalNavigator
)

Now you can use ModalStack in any _layout.tsx file.

Apps Onestack.Dev Data Docs Faq (`apps/onestack.dev/data/docs/faq.mdx`) Copy Section

title: FAQ Copy Chapter

Why Vite? Copy Section

It feels light and simple, runs fast and is easy to customize. It tree shakes well, has tons of web features, and has best-in-class types, documentation, type-docs, RFCs and community. It also has a huge ecosystem and responsive team.

Is this production ready? Copy Section

Yes! Thanks to many web bug fixes, tests and improvements, and One's own native bundler and modules, One is now generally production ready. See the Status documentation for more details.

Does this use Metro? Copy Section

No. One bundles native apps with Rolldown, the same bundler that builds web, so both platforms share one pipeline. Metro mode still exists as an opt-in.

How does this relate to Expo Router? Copy Section

One started as a fork of Expo Router but has since diverged significantly. We aim to maintain API compatibility where possible.

Why use One instead of Expo Router? Copy Section

One runs on Vite, which is fast, light, and has a massive ecosystem with best-in-class TypeScript support. One achieves significantly higher Lighthouse scores thanks to render modes, optimized loading strategies, and proper code splitting - you can hit 100 on Lighthouse while sharing nearly all your code with native.

With render modes, you can choose SSG, SSR, or SPA on a per-page basis - Expo Router is SPA-only on web. One includes a Hono-based production server out of the box and deploys to Vercel or Cloudflare with a single config option.

One also adds dev tools (Alt+Space) with SEO preview, route debugging, loader timing, error tracking, and a source inspector. Plus middleware for request interception and auth, and typed loaders that run on the server and tree-shake out of client bundles.

Expo Router does have features One lacks, like use dom and RSC support. We encourage you to evaluate both and choose based on your needs.

Will you support RSC? Copy Section

No, we find the complexity trade-off not worth it. One supports SSG, SPA, and SSR with loaders, and we recommend pairing with a sync engine like Zero for data. A simplified one-way RSC could work, which we'll continue to evaluate.

What platforms does One support? Copy Section

macOS (stable), Linux (stable), and Windows (early, not officially supported). See the Status documentation for details.

Can I use One for web-only or native-only projects? Copy Section

Yes. One works great as a web-only framework - you don't even need react-native as a dependency. For native-only, you can skip web-specific features like SSG/SSR. One is designed to be flexible whether you're targeting one platform or both.

How does One compare to Next.js? Copy Section

One takes a simpler approach: no RSC, no complex server/client boundaries. Instead, One uses loaders for data fetching (similar to Remix) and recommends pairing with a sync engine like Zero for real-time data. One also targets React Native alongside web with a single codebase, which Next.js doesn't support.

That said, One provides many things out of the box: image optimization with blur placeholders, dynamic OpenGraph images, middleware, automatic sitemaps, dev tools, a production Hono server, API routes, typed routes, scroll restoration, and a loading progress bar. See Features for the full list.

How does One compare to TanStack Start? Copy Section

Both are modern Vite-based frameworks with type safety and flexible rendering. One uses file suffixes (page+ssg.tsx, page+ssr.tsx) to set render modes while TanStack uses route property configuration. One also supports a global defaultRenderMode.

In One, SSG routes run loaders at build time and output static HTML. TanStack's "static prerendering" is a post-build crawl - a different model. One includes a Hono server out of the box while TanStack Start requires setting up Nitro or deploying to specific platforms. One's loaders run on the server and tree-shake out of client bundles, while TanStack's loaders are isomorphic (run on server, then again on client during navigation). And One targets web and native with shared routes and loaders - TanStack Start is web-only.

Both are great choices for web - One is the better fit if you need cross-platform or prefer the simpler file-based approach.

What's the difference between SSG, SSR, and SPA? Copy Section

SSG (Static Site Generation) pre-renders pages at build time - fast and cacheable, ideal for mostly-static content. SSR (Server Side Rendering) renders on each request - good for dynamic content that needs SEO. SPA (Single Page Application) renders entirely on the client - simpler for highly dynamic dashboards. See Render Modes for details.

Can I use my existing React Native libraries? Copy Section

Yes. For libraries that have issues with Vite, One provides a patches system to fix common problems like Flow types or JSX in .js files.

How do I deploy a One app? Copy Section

One includes a Hono server out of the box - just run one build && one serve. You can also deploy to Vercel or Cloudflare with a single config option.

What's the npm package? Copy Section

It's one, thanks to Dan Maier.

Can I develop iOS apps on Windows or Linux? Copy Section

Yes. With EAS Build, you can build iOS apps in the cloud from any platform. For local development, you can test on Android and web, then build iOS when ready. See Build or Run iOS for details.

What's the bundle size overhead? Copy Section

One itself adds some overhead, but not enough to affect Lighthouse scores in general.

The core routing and rendering logic is under 20KB gzipped, but it brings in React Navigation and generally react-native-web. You can swap for @tamagui/react-native-web-lite using an alias to save quite a bit of bundle size.

Can I use One with an existing React Native app? Copy Section

Yes. One can be added incrementally to existing React Native projects. Start by installing one and setting up file-based routing alongside your existing navigation.

Does One support monorepos? Copy Section

Yes. One works well in monorepos with tools like Turborepo, Nx, or pnpm workspaces. Configure your workspace's package resolution and One will respect it.

Apps Onestack.Dev Data Docs Features (`apps/onestack.dev/data/docs/features.mdx`) Copy Section

title: Features Copy Chapter

See the Status document for the status of features.

Vite Copy Chapter

The One Vite Plugin automates away much of the setup & boilerplate required for cross-platform React Native & web development.

Out of the box, the One Vite plugin does the following:

• Sets up a file system router in the ./app folder
• Generates types for routes and updates them when routes change
• Enables loaders and tree shakes them out on client using babel-dead-code-elimination
• Supports loader HMR with watchFile for instant content updates during development
• Enables the patches option that allows for easy node_module patching
• Uses React 19 for both native and web
• Adds vite-tsconfig-paths plugin, unless it detects you've added it already
• Loads .env file into process.env before running anything using dotenv
• Adds a well-configured tsconfig.json if it doesn't exist
• Enables ?imagedata imports for automatic image dimensions and blur placeholders
• Supports .inline.css files to inline critical CSS and prioritize layout CSS before scripts
• Configures native to resolve "react-native" export field in package.json
• Enforces environment guard imports (server-only, client-only, native-only, web-only) that prevent modules from being used in the wrong build environment
• Configures platform-specific extensions web|server|native|ios|android for extensions ts|tsx|js|mjs, eg .ios.ts, .server.ts
• Adds a ssr-css plugin that enables perfect dev-mode CSS on first load, matching production
• Configures a wide variety of optimizeDeps presets for React Native library compatibility
• Patches a large number of known-bad node_modules to work with Vite
• Ensures optimized deps across all routes are found before first load, avoiding hard reloads and slow loads in development mode

Universal Copy Chapter

• Uses React Navigation routing and truly native layouts
• Adds loaders that work on native and web
• Adds layout loaders - layouts can export loader() just like pages
• Adds useMatches hook to access all matched route data
• Adds useMatch to find a specific route's loader data by route ID
• Adds usePageMatch to get the current page's match
• Adds a Link component for navigation
• Adds useSearchParams for URLSearchParams API
• Adds a wide variety of hooks for routing
• Exposes One.UI.SafeArea with first-party native and web implementations
• Adds `` component for declarative route guarding
• Adds useBlocker hook for blocking navigation with confirmation
• Adds route validation with validateParams and validateRoute
• Adds loaderCache for deduplicating concurrent SSR loader calls with optional TTL

Native Copy Chapter

• Implements a custom bundle output with React Native compatible commonjs
• Implements custom hot reloading that works with commonjs
• Implements a custom bridge to React Native for debug logging
• Implements logic to support importing assets, like images
• Tree-shakes server code from native bundles automatically
• Auto-detects and configures NativeWind support
• Auto-detects and configures Reanimated support
• Stack Header Composition API for declarative native header configuration

Web Copy Chapter

• Adds serve command that sets up a Hono server for production with optional cluster mode for multi-core scaling
• Implements SPA, SSG, and SSR style routing on a per-page and global basis
• Server rendering - find JS and CSS for all nested routes and layouts and hoists it to header to avoid waterfalls and flickering
• Smart link prefetching that predicts navigation using mouse trajectory
  • Doesn't require up-front route map so no scaling cost
• Automatically handles scroll restoration and allows configuration
• Adds scroll position groups for independent scroll areas
• Adds route masks for displaying different URLs
• Adds an easy redirects option
• Adds generateStaticParams export for SSG and SSR routes
• Implements API routes
• Adds a page loading progress bar
• Swaps query-string and url-parse libraries to save ~20Kb
• Adds a Redirect component
• Supports middleware for request interception and shared context
• Deploy to Vercel or Cloudflare workers with a single config option
• Automatic sitemap generation with per-route overrides
• SPA shell rendering - render the root layout into HTML for SPA pages so users see nav, head tags, and CSS immediately while page content loads client-side

Devtools Copy Chapter

• Dev Tools Panel - Press Alt+Space to open the spotlight menu with SEO Preview, Route Info, Loader Timing, and Errors panels
• Source Inspector - Hold Option (Mac) or Alt (Windows/Linux) and click any element to open in your editor

Build Copy Chapter

• Parallel builds with worker threads for ~40% faster static page generation

Extras Copy Chapter

• Exports a variety of helpful utility functions
• Guide for MDX support
• Guide for light and dark mode
• Guide for optimized images with ?imagedata imports

Apps Onestack.Dev Data Docs Guides Authentication (`apps/onestack.dev/data/docs/guides-authentication.mdx`) Copy Section

title: Authentication Copy Chapter

This guide covers authentication patterns for One apps, from simple session management to full OAuth flows. One's unique combination of middleware, loaders, and cross-platform support gives you flexibility in how you protect routes.

Approaches Copy Chapter

There are three main approaches to authentication:

Self-hosted libraries like Better Auth or Auth.js run on your own server with your own database. You get full control over user data while the library handles the complexity of OAuth flows, session management, and security best practices. This is our recommended approach.

Hosted providers like Clerk or Supabase Auth manage everything for you including infrastructure. Fastest to set up but user data lives on their servers.

Custom auth means implementing everything yourself - password hashing, session management, token validation, OAuth flows. Only recommended if you have very specific requirements.

Session Context Copy Chapter

The foundation of any auth system is a session context that tracks auth state across your app.

import { createContext, useContext, useState, useEffect, type PropsWithChildren } from 'react'
import { storage } from './storage'

type AuthContextType = {
  signIn: (token: string) => void
  signOut: () => void
  session: string | null
  isLoading: boolean
}

const AuthContext = createContext<AuthContextType | null>(null)

export function useSession() {
  const ctx = useContext(AuthContext)
  if (!ctx) {
    throw new Error('useSession must be used within SessionProvider')
  }
  return ctx
}

export function SessionProvider({ children }: PropsWithChildren) {
  const [session, setSession] = useState<string | null>(null)
  const [isLoading, setIsLoading] = useState(true)

  useEffect(() => {
    storage.get('session').then((token) => {
      setSession(token)
      setIsLoading(false)
    })
  }, [])

  const signIn = (token: string) => {
    storage.set('session', token)
    setSession(token)
  }

  const signOut = () => {
    storage.remove('session')
    setSession(null)
  }

  return (
    <AuthContext.Provider value={{ signIn, signOut, session, isLoading }}>
      {children}
    </AuthContext.Provider>
  )
}

Cross-Platform Storage Copy Section

For token storage, use a cross-platform storage library. Popular options:

• react-native-mmkv - Fast key-value storage (~30x faster than AsyncStorage), works on web and native
• Zustand with persist middleware - State management with built-in storage abstraction
• One.SecureStore - Keychain and Keystore storage for sensitive tokens (native only)

Create a platform-specific abstraction using One's file extensions:

features/auth/
├── storage.ts        # Shared interface
├── storage.web.ts    # localStorage or MMKV for web
└── storage.native.ts # MMKV or One.SecureStore for native

This keeps your auth context clean while each platform uses appropriate secure storage.

Protected Routes Copy Chapter

There are two approaches to protecting routes in One:

Declarative with `` Copy Section

The `` component completely filters out routes when its guard prop is false. This is ideal when routes should be invisible to unauthorized users:

import { Stack, Protected } from 'one'
import { useSession } from '~/features/auth/ctx'

export default function AppLayout() {
  const { session, isLoading } = useSession()

  if (isLoading) return null

  return (
    <Stack>
      <Stack.Screen name="index" options={{ title: 'Home' }} />
      <Protected guard={!!session}>
        <Stack.Screen name="dashboard" options={{ title: 'Dashboard' }} />
        <Stack.Screen name="settings" options={{ title: 'Settings' }} />
      </Protected>
      <Protected guard={session?.role === 'admin'}>
        <Stack.Screen name="admin" options={{ title: 'Admin' }} />
      </Protected>
    </Stack>
  )
}

When session is null, attempts to navigate to /dashboard or /settings are blocked entirely - the routes don't exist in the navigation state.

Redirect Guard Copy Section

Protect routes using a layout guard that checks auth state and redirects unauthorized users. This approach allows deep linking to protected pages - users are redirected to login, then can return to their original destination.

<RouteTree
routes={[
{ name: '_layout.tsx', description: 'Root layout with SessionProvider' },
{ name: 'login.tsx', description: 'Public - login page' },
{ name: '(app)', children: [
{ name: '_layout.tsx', description: 'Auth guard - redirects if not logged in' },
{ name: 'index.tsx', description: 'Protected home' },
{ name: 'profile.tsx', description: 'Protected profile' },
] },
]}
/>

import { Slot } from 'one'
import { SessionProvider } from '~/features/auth/ctx'

export default function RootLayout() {
  return (
    <SessionProvider>
      <Slot />
    </SessionProvider>
  )
}

import { Redirect, Slot, useFocusEffect, useRouter } from 'one'
import { useSession } from '~/features/auth/ctx'

export default function AppLayout() {
  const { session, isLoading } = useSession()
  const router = useRouter()

  // Re-check auth when screen focuses (important for native)
  useFocusEffect(() => {
    if (!isLoading && !session) {
      router.replace('/login')
    }
  }, [isLoading, session])

  if (isLoading) {
    return null
  }

  if (!session) {
    return <Redirect href="/login" />
  }

  return <Slot />
}

The useFocusEffect ensures auth is re-checked when returning to a screen on native, where screens may stay mounted in memory.

Redirect Logged-In Users Copy Section

Keep authenticated users away from auth pages:

import { Redirect, useRouter } from 'one'
import { useSession } from '~/features/auth/ctx'

export default function LoginPage() {
  const { session } = useSession()
  const router = useRouter()

  if (session) {
    return <Redirect href="/" />
  }

  const handleLogin = async () => {
    // ... your login logic
    router.replace('/')
  }

  return (
    <Button onPress={handleLogin}>
      Sign In
    </Button>
  )
}

Middleware Authentication Copy Chapter

One's middleware runs on the server before your route, making it ideal for auth checks.

Protect API Routes Copy Section

import { createMiddleware } from 'one'
import { validateToken } from '~/features/auth/server'

export default createMiddleware(async ({ request, next, context }) => {
  const token = request.headers.get('authorization')?.replace('Bearer ', '')

  if (!token) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 })
  }

  try {
    const user = await validateToken(token)
    context.user = user
  } catch {
    return Response.json({ error: 'Invalid token' }, { status: 401 })
  }

  return await next()
})

Loader Authentication Copy Chapter

Check auth in loaders for SSR pages. Loaders run on the server, so redirect() works for both direct page loads and client-side <Link> navigation — the protected page never renders and no sensitive data reaches the client.

import { redirect, useLoader } from 'one'
import type { LoaderProps } from 'one'
import { validateSession } from '~/features/auth/server'

export async function loader({ request }: LoaderProps) {
  const session = await validateSession(request)

  if (!session) {
    throw redirect('/login')
  }

  const user = await getUser(session.userId)
  return { user }
}

export default function ProfilePage() {
  const { user } = useLoader(loader)

  return (
    <View>
      <Text>Welcome, {user.name}</Text>
    </View>
  )
}

Both throw redirect() and return redirect() work — throw is often cleaner since it stops execution and makes it obvious the remaining code won't run.

Use +ssr routes for protected pages so loaders run on every request, including client-side navigation. This ensures auth is always checked server-side.

Note: Component JavaScript is always downloadable (same as every framework). Loaders protect data — use them to ensure sensitive data never reaches unauthorized clients.

OAuth Integration Copy Chapter

GitHub OAuth Example Copy Section

import { betterAuth } from 'better-auth'
import { jwt, bearer } from 'better-auth/plugins'

export const auth = betterAuth({
  database: process.env.DATABASE_URL,

  plugins: [
    jwt({ expirationTime: '7d' }),
    bearer(),
  ],

  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    },
  },
})

import { auth } from '~/features/auth/server'

export const GET = (req: Request) => auth.handler(req)
export const POST = (req: Request) => auth.handler(req)

import { authClient } from '~/features/auth/client'

export default function LoginPage() {
  const handleGitHubLogin = () => {
    authClient.signIn.social({ provider: 'github' })
  }

  return (
    <Button onPress={handleGitHubLogin}>
      Sign in with GitHub
    </Button>
  )
}

Logout Copy Chapter

import { useRouter } from 'one'
import { useSession } from './ctx'
import { authClient } from './client'

export function useLogout() {
  const router = useRouter()
  const { signOut } = useSession()

  const logout = async () => {
    try {
      await authClient.signOut()
      signOut()
      router.replace('/login')
    } catch (error) {
      console.error('Logout failed:', error)
    }
  }

  return { logout }
}

Related Copy Chapter

• Protected - Declarative route protection
• Middlewares - Server-side request interception
• Loaders - Data loading with auth
• API Routes - Creating API endpoints

Apps Onestack.Dev Data Docs Guides Css (`apps/onestack.dev/data/docs/guides-css.mdx`) Copy Section

title: CSS Loading Copy Chapter

One automatically optimizes CSS loading in production builds. Layout CSS is loaded before scripts to prevent flash of unstyled content (FOUC), and you can mark individual CSS files as inline to embed them directly into the HTML.

CSS Loading Order Copy Chapter

In production builds, One separates CSS into two categories:

• Layout CSS — CSS imported by _layout files. Loaded before any JavaScript to prevent FOUC.
• Page CSS — CSS imported by page components. Loaded after scripts.

This happens automatically based on your route structure. No configuration needed.

Inline CSS (`.inline.css`) Copy Chapter

For CSS that must be available before the first paint, use the .inline.css file extension. This inlines the CSS content directly as a <style> tag in the HTML <head>, eliminating the network request entirely.

// inlined as <style> in HTML — zero network latency
import './critical-styles.inline.css'

// loaded via <link> tag — normal network request
import './non-critical-styles.css'

When to use `.inline.css` Copy Section

Use .inline.css for CSS that:

• Defines the page layout structure (prevents layout shift)
• Sets background colors or fonts visible above the fold
• Is small enough that inlining doesn't bloat the HTML (under ~10KB)

Don't use .inline.css for:

• Large CSS files (defeats the purpose — better as a cacheable <link>)
• CSS only needed after user interaction
• Component-specific CSS that isn't visible on first paint

How it works Copy Section

1. The .inline.css extension is detected during the build — Vite processes the CSS normally
2. The plugin tracks which CSS files should be inlined
3. At HTML generation time, inline CSS is read from the build output and inlined as <style> tags
4. Other CSS remains as <link rel="stylesheet"> tags

With `inlineLayoutCSS` Copy Section

.inline.css works independently of the inlineLayoutCSS config option:

• inlineLayoutCSS: true — inlines ALL CSS as <style> tags
• .inline.css — inlines only the marked files, leaves the rest as <link> tags
• Both together — inlineLayoutCSS takes precedence and inlines everything

TypeScript Copy Section

The .inline.css extension works with any CSS file. Since it's a side-effect import (no default export), TypeScript handles it without additional type declarations:

import './styles.inline.css' // works out of the box

Comparison Copy Chapter

Apps Onestack.Dev Data Docs Guides Dark Mode (`apps/onestack.dev/data/docs/guides-dark-mode.mdx`) Copy Section

title: Dark Mode Copy Chapter

Supporting SSR safe styling while also supporting Native and web requires a lot of work,
until now.

There's about one cross-platform React style library that has excellent SSR support - Tamagui 👌.

Tamagui gives you styling out of the box that works perfectly with no flickers, and even renders properly with JS turned off (give it a try on this very page).

Using our style-library-agnostic @vxrn/color-scheme library, you can also let your users choose between three options: light, dark, or system settings - also, fully SSR safe. one re-exports everything from @vxrn/color-scheme, so you can import these from either package.

Finally, there's another wrinkle in the theme-color meta tag - it also requires some fancy scripting to be SSR safe. Luckily, @vxrn/color-scheme helps again with the MetaTheme component.

Here's a complete example in just a few lines of code, all set up in your root _layout.tsx file. We're using Tamagui, but if you just want light/dark mode without SSR, you can swap out your own solution.

import type { ReactNode } from 'react'
import { MetaTheme, SchemeProvider, Slot, useUserScheme } from 'one'
import { TamaguiProvider, Theme } from 'tamagui'
import config from '../tamagui.config'

export default function Layout() {
  return (
    <SchemeProvider>
      <MetaTheme darkColor="#050505" lightColor="#ffffff" />
      <TamaguiRoot>
        <Theme name="yellow">
          <Slot />
        </Theme>
      </TamaguiRoot>
    </SchemeProvider>
  )
}

const TamaguiRoot = ({ children }: { children: ReactNode }) => {
  const userScheme = useUserScheme()
  return (
    <TamaguiProvider disableInjectCSS config={config} defaultTheme={userScheme.value}>
      {children}
    </TamaguiProvider>
  )
}

SchemeProvider renders a small inline script that sets a t_dark or t_light class on <html> before the page paints, reading the stored setting or falling back to the system preference. It accepts:

• defaultScheme: the scheme to use when the user has stored no preference, instead of the system preference.
• forceScheme: lock the page to light or dark, ignoring stored and system preferences.
• getClassName: change the class name for a scheme (defaults to (name) => `t_${name}`).

MetaTheme takes darkColor and lightColor. Its inline script picks one before hydration; after that, an optional color prop replaces the scheme's color while it is set. useUserScheme() returns { setting, value, set }: the stored setting (system, light, or dark), the resolved scheme (light or dark), and a setter. Outside React, use getUserScheme, setUserScheme, and onUserSchemeChange; useSystemScheme and getSystemScheme read the operating system's scheme.

Now lets make a toggle button:

import { Moon, Sun, SunMoon } from '~/components/icons'
import { useUserScheme } from 'one'
import { Button } from 'tamagui'

const schemeSettings = ['light', 'dark', 'system'] as const

export function ThemeToggleButton() {
  const { setting, set } = useUserScheme()
  const Icon = setting === 'system' ? SunMoon : setting === 'dark' ? Moon : Sun
  const next = schemeSettings[(schemeSettings.indexOf(setting) + 1) % schemeSettings.length]

  return (
    <Button
      circular
      icon={<Icon size={20} />}
      aria-label={`Color scheme: ${setting}`}
      onPress={() => set(next)}
    />
  )
}

Each press cycles light, dark, and system. The stored setting survives reloads, and with system the page follows the operating system's preference.

Apps Onestack.Dev Data Docs Guides Deep Linking (`apps/onestack.dev/data/docs/guides-deep-linking.mdx`) Copy Section

title: Deep Linking Copy Chapter

Deep linking lets external URLs open a specific screen in your app on web, iOS, and Android. One handles deep links by stripping a configured prefix from the incoming URL and matching the remaining path against your file-system routes.

Quick Start Copy Chapter

Configure router.linking in your Vite config and register the same scheme in your native app manifest.

import { one } from 'one/vite'

export default {
  plugins: [
    one({
      native: {
        app: {
          name: 'MyApp',
          scheme: 'myapp',
          ios: { bundleId: 'com.example.myapp' },
          android: { applicationId: 'com.example.myapp' },
        },
      },
      router: {
        linking: {
          scheme: 'myapp',
          prefixes: ['https://example.com/app'],
        },
      },
    }),
  ],
}

With this, opening myapp://settings/profile or https://example.com/app/settings/profile (after universal-link verification) routes to app/settings/profile.tsx.

How Prefix Matching Works Copy Chapter

Each entry in prefixes is an exact URL prefix that gets stripped from incoming deep links before route matching. A scheme is shorthand: 'myapp' expands to 'myapp://' and 'myapp:///' automatically.

Prefixes match at clean boundaries — the URL must be exactly the prefix, or continue with /, ?, or #:

When multiple prefixes match the same URL, the longest one wins.

The native app manifest registers URLs with iOS and Android. router.linking tells One how to strip those URLs before matching routes, so configure the scheme in both places.

`OneLinkingConfig` Reference Copy Chapter

type OneLinkingConfig = {
  scheme?: string | string[]
  prefixes?: string[]
  filter?: (url: string) => boolean
}

• scheme — one or more custom app schemes. Each scheme is expanded internally to ${scheme}:// and ${scheme}:/// URL prefixes. Schemes should also be registered in your native app manifest.
• prefixes — fully qualified URL prefixes to strip before route matching. Use this for universal links ('https://example.com/app') or host-bearing custom scheme URLs ('myapp://app').
• filter — optional predicate that gates which incoming URLs are handled. Functions can't be inlined into the generated entry, so this can only be set programmatically (see below).

The `getLinking` Helper Copy Chapter

getLinking is a typed identity helper for defining a linking config in TypeScript. It's useful when you want to share the config across files or pass it programmatically.

import { getLinking } from 'one'

export const linking = getLinking({
  scheme: 'myapp',
  prefixes: ['https://example.com/app'],
})

Programmatic Configuration (with `filter`) Copy Chapter

To use a filter function, write your own entry that calls createApp({ linking }) directly. The Vite plugin's router.linking only accepts JSON-serializable fields.

import { createApp, getLinking } from 'one'

const linking = getLinking({
  scheme: 'myapp',
  prefixes: ['https://example.com/app'],
  filter: (url) => !url.includes('/admin'),
})

createApp({
  routes: import.meta.glob('./app/**/*'),
  routerRoot: 'app',
  linking,
})

iOS Setup Copy Chapter

The scheme in native.app lands in Info.plist after running one prebuild. To verify:

plutil -p ios/MyApp/Info.plist | grep -A 4 CFBundleURLTypes

Test a deep link against a running simulator:

xcrun simctl openurl booted myapp://settings/profile

For universal links (https://example.com/app/...), follow Apple's associated domains setup and add the entitlement.

Android Setup Copy Chapter

one prebuild registers the native.app scheme in AndroidManifest.xml. Add universal-link hosts to the generated native project, then test with:

adb shell am start -W -a android.intent.action.VIEW -d "myapp://settings/profile"

Web Behavior Copy Chapter

On web, deep linking is just URL routing — no prefix-stripping is needed because the browser already provides the path via window.location. The configured prefixes and scheme are still accepted for API parity but are inert on web.

Inspecting Routes with `useSitemap` Copy Chapter

Use useSitemap to render a list of all routes — handy for debug screens or generating link previews while testing deep links.

Related Copy Chapter

• useSitemap — list every route in your app
• Configuration — full Vite plugin reference
• Routing Overview — file-system routing fundamentals

Apps Onestack.Dev Data Docs Guides Deployment (`apps/onestack.dev/data/docs/guides-deployment.mdx`) Copy Section

title: Deployment Copy Chapter

One supports multiple deployment targets for web applications. Choose the target that best fits your infrastructure needs.

Configuration Copy Chapter

Set your deployment target in vite.config.ts:

import { one } from 'one/vite'

export default {
  plugins: [
    one({
      web: {
        deploy: 'node' // 'node' (default), 'vercel', or 'cloudflare'
      },
      build: {
        // fail the build if secrets leak into client bundles
        securityScan: 'error'
      }
    })
  ]
}

We recommend setting securityScan: 'error' for production deployments to prevent accidentally shipping API keys or tokens in client-facing JavaScript. See Configuration: build.securityScan for details.

Deployment Targets Copy Chapter

Node (Default) Copy Section

The default deployment target outputs a Node.js server using Hono. This is suitable for any Node.js hosting environment.

# Build for production
npx one build

# Start the production server
npx one serve

The build output is in the dist directory:

• dist/client - Static assets and client-side bundles
• dist/server - Server-side rendering bundles
• dist/api - API route handlers

You can deploy this to any platform that supports Node.js:

• Docker: Create a Dockerfile that runs npx one serve
• Render, Fly.io: Point to your repo and set the start command to npx one serve
• AWS, GCP, Azure: Deploy as a containerized application or using their Node.js runtimes

Vercel Copy Section

One supports deploying to Vercel's serverless infrastructure using the Build Output API.

import { one } from 'one/vite'

export default {
  plugins: [
    one({
      web: {
        deploy: 'vercel'
      }
    })
  ]
}

Project Setup

1. Add vercel.json to your project root:

{
  "framework": null,
  "cleanUrls": true,
  "buildCommand": "npx one build",
  "installCommand": "npm install"
}

Setting framework: null tells Vercel to use the pre-built output from the Build Output API instead of auto-detecting a framework.

The cleanUrls: true setting is important for SSG routes - it allows URLs like /about to serve about.html without needing the .html extension. Without this, direct navigation to SSG pages will 404.

2. Install the Vercel CLI (optional, for manual deploys):

npm install vercel

Git Push Deploys

The easiest way to deploy is connecting your Git repository to Vercel:

1. Go to vercel.com/new
2. Import your Git repository
3. Vercel auto-detects settings from vercel.json
4. Click Deploy

Once connected, every push to your main branch triggers a production deploy. Pull requests get preview deployments automatically.

Manual CLI Deploy

For manual deploys or CI/CD pipelines:

# Build for Vercel
npx one build

# Deploy using Vercel CLI
vercel deploy --prebuilt

The --prebuilt flag tells Vercel to use the pre-generated output in .vercel/output instead of running its own build process.

For production deploys:

vercel deploy --prebuilt --prod

Testing Production Build Locally

You can do a basic sanity check of your production build locally:

# Build the app
npx one build

# Serve the production build
npx one serve

Note: This runs the Hono server from dist/, not the actual Vercel serverless functions. It's useful for catching build errors and checking that pages render correctly, but it's not a perfect simulation of the Vercel environment.

For true Vercel testing, use a preview deploy:

# Deploy a preview (not production)
vercel deploy --prebuilt

Every push to a non-main branch also triggers a preview deployment automatically when using Git integration. This is the most reliable way to test before promoting to production.

What Gets Built

When targeting Vercel, One generates:

• .vercel/output/static - Static assets served from Vercel's Edge Network
• .vercel/output/functions - Serverless functions for:
  • SSR pages (+ssr.tsx files)
  • API routes (app/api/**)
  • Loaders (data fetching functions)

Static routes (+ssg.tsx) are pre-rendered to .vercel/output/static as HTML files.

Environment Variables

Set environment variables in your Vercel project dashboard under Settings > Environment Variables:

# Required for SSR and API routes
ONE_SERVER_URL=https://your-app.vercel.app

For local development, add to .env.local:

ONE_SERVER_URL=http://localhost:8081

Vercel Project Settings

When using vercel.json, settings are auto-configured. If you need to configure manually in the Vercel dashboard:

1. Framework Preset: Other
2. Build Command: npx one build
3. Output Directory: .vercel/output
4. Install Command: npm install (or bun install, pnpm install)

Static-Only Sites

If your site only uses SSG routes (+ssg.tsx) without SSR, loaders, or API routes, you can simplify:

one({
  web: {
    deploy: 'vercel',
    defaultRenderMode: 'ssg',
  }
})

This generates only static files with no serverless functions, resulting in faster deploys and lower costs.

Troubleshooting

Build fails with "Cannot find module": Ensure all dependencies are in dependencies, not devDependencies, if they're used at runtime.

404 on dynamic routes: Check that your route files use the correct suffix (+ssr.tsx for server-rendered, +ssg.tsx with generateStaticParams for static).

Environment variables not available: Variables must be added in Vercel dashboard and redeployed. Local .env files are not uploaded.

Slow cold starts: Consider using +ssg.tsx for routes that don't need real-time data. Static routes have no cold start.

Static Export Copy Chapter

If you're only using SSG and SPA routes without loaders or API routes, you can statically serve the dist/client directory from any static hosting:

• Netlify
• GitHub Pages
• Cloudflare Pages (static only)
• AWS S3 + CloudFront
• Any CDN or static file server

npx one build
# Upload dist/client to your static host

Cloudflare Workers Copy Section

One supports deploying to Cloudflare Workers with full SSR, API routes, and edge performance.

import { one } from 'one/vite'

export default {
  plugins: [
    one({
      web: {
        deploy: 'cloudflare'
      }
    })
  ]
}

Build and Deploy

# Build for Cloudflare
npx one build

# Deploy using Wrangler
wrangler deploy --config dist/worker/wrangler.json

Continuous Deployment

Wrangler is non-interactive in CI, so authenticate with an API token and
account ID instead of wrangler login. Store both as secrets in your CI
provider:

• CLOUDFLARE_API_TOKEN: a token with the Edit Cloudflare Workers
  permission, scoped to the account holding the worker
• CLOUDFLARE_ACCOUNT_ID: the account ID the worker deploys to

A GitHub Actions job then only needs to build and deploy:

- run: npx one build
- run: wrangler deploy --config dist/worker/wrangler.json
  env:
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

See Cloudflare's GitHub Actions guide for token setup details.

What Gets Built

When targeting Cloudflare, One generates:

• dist/worker/index.js - The Cloudflare Worker entry point
• dist/worker/wrangler.json - Wrangler configuration for the generated worker
• dist/client - Static assets served from Cloudflare's edge
• dist/server - Server-side bundles (lazy-loaded per route)
• dist/api - API route handlers (lazy-loaded per route)
• dist/middlewares - Middleware bundles used by the worker runtime

Lazy Loading

One uses a lazy loading pattern for Cloudflare Workers. Route modules are loaded on-demand when matched, not all upfront. This improves cold start times for apps with many routes.

The generated worker config lives at dist/worker/wrangler.json and is ready to deploy with Wrangler. The worker serves static assets from ../client and loads route bundles from the generated dist/server, dist/api, and dist/middlewares outputs as requests come in.

{
  "main": "index.js",
  "no_bundle": true,
  "rules": [{ "type": "ESModule", "globs": ["assets/**/*.js", "assets/**/*.mjs"] }],
  "assets": {
    "directory": "../client",
    "binding": "ASSETS",
    "run_worker_first": true
  }
}

Accessing Bindings and `waitUntil`

API route handlers receive the worker runtime's env and executionCtx on their second argument as worker:

import { createAPIRoute } from 'one'

export const POST = createAPIRoute(async (request, { worker }) => {
  // env holds the bindings you defined in wrangler.json (KV, D1, R2, secrets, ASSETS)
  const db = worker?.env?.DB

  // waitUntil keeps the worker alive for fire-and-forget work after the
  // response is sent — useful for analytics, logging, cache warming, etc.
  worker?.executionCtx?.waitUntil(trackAsync(request))

  return Response.json({ ok: true })
})

worker is undefined outside the worker runtime (dev/Node), so the optional chaining keeps the handler runtime-portable. See the API Routes doc for full details.

Requirements

• Cloudflare Workers with nodejs_compat compatibility flag (auto-configured)
• Wrangler CLI for deployment

Wrangler Configuration

The generated worker config is ready to use. To customize it, create your own wrangler.jsonc in your project root and One will merge it into the generated dist/worker/wrangler.json.

One preserves build-required settings like main, assets.directory, assets.binding, assets.run_worker_first, the generated worker chunk rules, and it always includes nodejs_compat in compatibility_flags.

Key settings:

{
  "name": "your-app-name",
  "compatibility_flags": ["nodejs_compat"],
  "assets": { "directory": "../client" }
}

Apps Onestack.Dev Data Docs Guides Eas (`apps/onestack.dev/data/docs/guides-eas.mdx`) Copy Section

title: Build and Deliver Native Apps with EAS Copy Chapter

EAS Build and EAS Update are covered in
Coming from Expo. For One's own
over-the-air updates, see Over-the-air Updates.

Apps Onestack.Dev Data Docs Guides Headless Web (`apps/onestack.dev/data/docs/guides-headless-web.mdx`) Copy Section

title: Headless Web Navigators Copy Chapter

On web, <Stack>, <Tabs>, and <Drawer> render headless: just the matched route's element. No tab bar, no header, no wrapper elements, no styles. Native is unchanged - react-navigation still renders full chrome exactly as before.

import { Tabs } from 'one'

export default function Layout() {
  return (
    <Tabs>
      <Tabs.Screen name="home" options={{ title: 'Home' }} />
      <Tabs.Screen name="feed" options={{ title: 'Feed' }} />
    </Tabs>
  )
}

On native this renders a bottom tab bar as usual. On web it renders only the focused tab's screen - no bar. Your site's own nav is your tab bar.

Why Copy Chapter

One's web build doesn't ship react-native-web. Rendering full react-navigation chrome (tab bars, headers, drawers) on web meant carrying RNW just to draw them, so on web the navigators stopped rendering any of that and instead expose the underlying navigation state as data. Bring your own DOM, Tamagui, or whatever you already use to build your site's chrome.

What each navigator renders by default Copy Chapter

• Stack: the focused screen. Screens with a presentation (sheet, modal, formSheet, ...) render as overlays above the base screen - inline with no floating chrome by default, or with real chrome once you mount Presentations.
• Tabs: the focused tab's screen, no bar.
• Drawer: the focused screen. Open state lives in navigation state - build your own sidebar with useDrawer.
• Slot: unchanged, it was always the identity.

Keeping screens mounted Copy Chapter

Set keepMounted on a screen and the navigator's default web view keeps it alive once you navigate away, hidden via React 19.2's <Activity mode="hidden"> instead of unmounting, so scroll position and form state survive.

<Stack.Screen name="settings" options={{ keepMounted: true }} />

It works the same in all three navigators. In Tabs and Drawer a screen is only kept once it has actually been focused, matching react-navigation's lazy behavior on native. Custom layouts render whatever they want, so they own this themselves - keepMounted is on every entry from useStack, useTabs, and useDrawer.

Building your own layout Copy Chapter

Add a component as a child of the navigator. It replaces the headless default on web.

// app/(tabs)/_layout.tsx, works on both platforms
import { Link, Tabs, useTabs } from 'one'

function WebTabBar() {
  const { screens, focused } = useTabs()

  return (
    <>
      <nav>
        {screens.map((tab) => (
          <Link
            key={tab.name}
            href={tab.href}
            className={tab.isFocused ? 'active' : undefined}
          >
            {tab.options.title}
          </Link>
        ))}
      </nav>
      {focused.element}
    </>
  )
}

export default function Layout() {
  return (
    <Tabs>
      <Tabs.Screen name="home" options={{ title: 'Home' }} />
      <Tabs.Screen name="feed" options={{ title: 'Feed' }} />
      <WebTabBar />
    </Tabs>
  )
}

The mechanical rule: a navigator child that is not config (Screen, Protected, Stack.Header) replaces the headless default on web, and is ignored on native. The same layout file works on both platforms. Native keeps rendering its usual chrome from the Screen config, while web renders WebTabBar instead. If a custom layout ever needs a different native version too, split it into a .web.tsx file the same way you would any other platform-specific component.

Each navigator has its own hook returning its full state: useStack, useTabs, useDrawer.

Sheets and modals Copy Chapter

Stack screens with presentation: 'sheet' or presentation: 'modal' work on web with no setup - they render inline, in place, with no floating position or backdrop (headless doesn't add styling for you).

To give them real sheet/modal chrome, mount Presentations once in your root layout:

// app/_layout.tsx
import { Presentations, Slot } from 'one'
import { Modal } from '~/interface/Modal'
import { Sheet } from '~/interface/Sheet'

export default function Layout() {
  return (
    <Presentations web={{ sheet: Sheet, modal: Modal }}>
      <Slot />
    </Presentations>
  )
}

Sheet and Modal are ordinary components receiving open, onOpenChange, options, screen, and children.

Any layout that declares a sheet or modal screen picks this up automatically, using the same presentation/sheetAllowedDetents vocabulary you'd write for native:

<Stack>
  <Stack.Screen
    name="compose"
    options={{ presentation: 'sheet', sheetAllowedDetents: [0.6, 1] }}
  />
</Stack>

Omit sheet or modal and that kind keeps its headless default, so you only need to write the presentations you actually use.

If your app renders react-native components on web Copy Chapter

The react-native to react-native-web alias is still there for your own code, so import { View } from 'react-native' keeps working on web. What changed is that One's own web output no longer contains any of it, so an app that doesn't import react-native itself never loads it.

One also stopped extracting react-native-web's generated stylesheet during SSR, since that only mattered when the framework rendered react-native components for you. If your app renders them on web and you want their styles in the server HTML instead of after hydration, do the extraction in your root layout:

import { Slot, useServerHeadInsertion } from 'one'
import { AppRegistry } from 'react-native'

export default function Layout() {
  useServerHeadInsertion(() => {
    AppRegistry.registerComponent('styles', () => () => null)
    // @ts-expect-error web-only api
    return AppRegistry.getApplication('styles', {}).getStyleElement()
  })

  return <Slot />
}

Longer term the recommendation is to drop react-native-web on web. It's in maintenance mode, and One gives you the DOM directly. Use Tamagui, React Strict DOM, or plain elements with CSS for shared primitives.

Native Copy Chapter

Native is unaffected by any of this. <Stack>, <Tabs>, and <Drawer> still render through React Navigation with real headers, a real bottom tab bar, and a real drawer. Nothing about your Screen config, screenOptions, or Stack.Header composition changes.

Related Copy Chapter

• Presentations
• useStack
• useTabs
• useDrawer
• Stack
• Tabs
• Drawer

Apps Onestack.Dev Data Docs Guides Images (`apps/onestack.dev/data/docs/guides-images.mdx`) Copy Section

title: Images Copy Chapter

One provides a built-in way to import images with their metadata at build time using the ?imagedata suffix. This gives you automatic width, height, and blur placeholder data without any runtime cost.

Setup Copy Chapter

Install sharp to enable image processing:

npm install sharp

If sharp is not installed, imports will still work but return 0 for dimensions and an empty blur placeholder. A console warning will be shown during build to remind you to install it.

Usage Copy Chapter

Import any image with the ?imagedata suffix:

import heroImage from '/hero.jpg?imagedata'

// heroImage = {
//   src: '/hero.jpg',
//   width: 1920,
//   height: 1080,
//   blurDataURL: 'data:image/jpeg;base64,...'
// }

The returned object can be spread directly onto any image component:

import heroImage from '/hero.jpg?imagedata'

// Native img element
<img {...heroImage} alt="Hero" />

// Or with explicit props
<img
  src={heroImage.src}
  width={heroImage.width}
  height={heroImage.height}
  style={{ backgroundImage: `url(${heroImage.blurDataURL})` }}
  alt="Hero"
/>

Import paths Copy Chapter

The plugin supports both public directory and relative imports:

// From public directory (starts with /)
import hero from '/images/hero.jpg?imagedata'

// Relative to current file
import avatar from './avatar.png?imagedata'
import logo from '../assets/logo.svg?imagedata'

TypeScript Copy Chapter

Types are included automatically. The import returns an ImageData object:

import type { ImageData } from 'one'

// ImageData = {
//   src: string
//   width: number
//   height: number
//   blurDataURL: string
// }

Blur placeholders Copy Chapter

The blur placeholder is a tiny (10px wide) base64-encoded JPEG that can be used as a low-quality image placeholder (LQIP) while the full image loads:

import hero from '/hero.jpg?imagedata'

function HeroImage() {
  const [loaded, setLoaded] = useState(false)

  return (
    <div style={{ position: 'relative' }}>
      {/* Blur placeholder */}
      <img
        src={hero.blurDataURL}
        width={hero.width}
        height={hero.height}
        style={{
          position: 'absolute',
          filter: 'blur(20px)',
          transform: 'scale(1.1)',
          opacity: loaded ? 0 : 1,
          transition: 'opacity 0.3s',
        }}
        alt=""
      />
      {/* Full image */}
      <img
        {...hero}
        onLoad={() => setLoaded(true)}
        alt="Hero"
      />
    </div>
  )
}

Programmatic usage Copy Chapter

For one-off usage or build scripts, use the getImageData helper:

import { getImageData } from 'one/image'

// Paths starting with / resolve from ./public
const heroData = await getImageData('/images/hero.jpg')
// { src: '/images/hero.jpg', width: 1920, height: 1080, blurDataURL: '...' }

// Or use relative paths from your current file
const logoData = await getImageData('../public/images/logo.png')

MDX frontmatter integration Copy Chapter

When using @vxrn/mdx, images in frontmatter are automatically processed with getMDX. If your MDX file has:

---
title: My Post
image: /images/post-hero.jpg
---

The frontmatter will include imageMeta with dimensions and blur placeholder:

import { getMDX } from '@vxrn/mdx'

const { frontmatter } = await getMDX(source, { publicDir: './public' })
// frontmatter.image = '/images/post-hero.jpg'
// frontmatter.imageMeta = { width: 1200, height: 630, blurDataURL: '...' }

Supported formats Copy Chapter

The plugin uses sharp for image processing, which supports:

• JPEG / JPG
• PNG
• WebP
• AVIF
• GIF
• TIFF
• SVG (dimensions only, no blur placeholder)

Benefits Copy Chapter

• Build-time processing - No runtime cost, dimensions are computed during build
• Prevents layout shift - Width and height allow browsers to reserve space before images load
• Blur placeholders - Improve perceived performance with LQIP technique
• Type-safe - Full TypeScript support with autocomplete
• Works everywhere - Compatible with any image component (native , React Native , Tamagui, etc.)
• MDX integration - Frontmatter images are automatically processed

Apps Onestack.Dev Data Docs Guides Ios Apis (`apps/onestack.dev/data/docs/guides-ios-apis.mdx`) Copy Section

title: Calling iOS APIs Copy Chapter

The iOS API reference lists the frameworks, types and members included in One's generated SDK bindings. It lives separately from these guides because it is regenerated from the same SDK symbol graphs and binding entries as the native code.

Start with a framework such as CoreBluetooth, then choose a type such as CBCentralManager. Each type page shows its Swift declarations, available TypeScript call shapes, iOS availability and any SDK documentation comments. Search the reference sidebar to find a type across frameworks.

Coverage describes the generated snapshot. A framework page also lists skipped declarations and explains why each is unavailable. Check the declaration's iOS version before calling it. Your app still needs Apple's required permissions, usage descriptions and entitlements.

For APIs with output parameters, leave those parameters out of the call. The returned object contains $ret for the return value and $out for the named output values.

Background method calls Copy Chapter

Use callSDKMethodAsync from one/ios-runtime to await an instance method that does blocking native work. It keeps the generated method's argument and return types:

import type { CNContactStore, CNSaveRequest } from 'one/ios/Contacts'
import { callSDKMethodAsync } from 'one/ios-runtime'

async function saveContacts(store: CNContactStore, request: CNSaveRequest) {
  await callSDKMethodAsync(store, 'execute', request)
}

A synchronous method runs on a background queue when it has no main actor requirement. Main actor methods and native async methods retain their declared execution rules. Choose a background call only for APIs that support background access. Methods requiring synchronous JavaScript callbacks are rejected before native execution.

Native failures throw an Error with code: 'E_SDK', the original NSError domain, and its numeric nativeCode. Use these fields to classify a failure independently of its localized message. Calls, returned functions, and subscription errors preserve the same metadata.

React state from native objects Copy Chapter

Two hooks from one/ios-runtime turn changing native values into React state. Each returns { status, value, error }, where status is 'pending', 'value' or 'error'. Subscriptions start when the component mounts and stop when it unmounts or its arguments change.

useSDKProperty(object, property) rerenders when a native property changes:

import { Text } from 'react-native'
import { Progress } from 'one/ios/Foundation'
import { useSDKProperty } from 'one/ios-runtime'

function DownloadProgress({ progress }: { progress: Progress }) {
  const state = useSDKProperty(progress, 'fractionCompleted')
  return <Text>{state.value ?? 0}</Text>
}

The generator chooses how to watch each property. Objective-C properties use key-value observing, and properties of Swift classes that adopt Observable use Observation tracking. TypeScript only accepts properties that can be watched one of these ways. Key-value observing reports a change only when the framework sends one, so check Apple's documentation to see whether a property supports it.

useSDKSequence(handle) follows an AsyncSequence or a Combine publisher and holds its latest element:

import { Text } from 'react-native'
import { NotificationCenter, NSNotification_Name } from 'one/ios/Foundation'
import { useSDKSequence } from 'one/ios-runtime'

const name = NSNotification_Name.init('app.refresh')
const notifications = NotificationCenter.default.notifications(name)

function LastRefresh() {
  const state = useSDKSequence(notifications)
  return <Text>{state.status === 'value' ? String(state.value.object) : 'waiting'}</Text>
}

The element type comes from the declaration, so state.value above is a Notification. An async sequence keeps iterating while no component listens, and a remounted component starts from its latest element. A publisher subscription starts fresh on each mount. Keep a handle you create in useMemo or module scope; a new handle on every render starts a new subscription. Pass null or undefined to leave the hook pending.

For app setup and custom native modules, see One Native setup and Swift and Kotlin.

Apps Onestack.Dev Data Docs Guides Ios Native (`apps/onestack.dev/data/docs/guides-ios-native.mdx`) Copy Section

title: Build or Run the Native iOS App Copy Chapter

This guide explains how to build and upload your iOS app to the App Store or TestFlight, or run it locally during development with custom native dependencies.

You'll use the prebuild command to generate the native code and Xcode project for iOS, open it with Xcode, and either run the app or archive it for distribution.

one prebuild generates the Xcode project from native.app in
vite.config.ts, and one run:ios launches it on a simulator. Apps that keep
Expo prebuild follow Coming from Expo.

Prebuild Copy Chapter

Before you can run or build your iOS app, you'll need to generate the native code and Xcode project for iOS.

Ensure the prebuild:native script is defined in your package.json:

{
  "scripts": {
    "prebuild:native": "one prebuild"
  }
 }

Then run:

yarn prebuild:native

This command may prompt you with some questions and could take a few minutes to install CocoaPods dependencies on its first run.

Once finished, your iOS project will be available in the ./ios directory and ready for use.

Running the App in Development Copy Chapter

Using `one run:ios` Copy Section

The simplest way to run your app after prebuild is using the CLI:

one run:ios

This will build and launch the app on your default iOS simulator. For Android, use one run:android.

Using Xcode Copy Section

Alternatively, you can open the .xcworkspace file in the ./ios directory. The filename will vary based on your app's name, but you can generally open it by running this command:

open ios/*.xcworkspace

Once Xcode opens, ➊ choose a simulator or physical device, and ➋ click the run button to build and launch the app.

Building for Production Copy Chapter

Open the .xcworkspace file from the ios directory. You can do this by running the following command:

open ios/*.xcworkspace

Once Xcode opens, follow these steps:

• ➊ Click your app project in the Project Navigator.
• ➋ Under “TARGETS,” select your app.
• ➌ Go to the “Signing & Capabilities” tab.
• ➍ Ensure “Automatically manage signing” is checked.
• ➎ Select a development team.

Once code signing is set up, click "Product" → "Archive" on the menu bar to start the Archive process.

After the archive process completes, Xcode will automatically open the Organizer window with your build. From there, click "Distribute App" to upload the app to the App Store or TestFlight.

Project Setup Copy Chapter

React Native Copy Section

You should add a react-native.config.cjs file in your project root to configure React Native to use Vite as the JS bundler during the native build process:

module.exports = require('one/react-native-config')

This routes native build bundling through One and links One's native SwiftUI,
Compose, effects, and safe area implementation through community autolinking.

One Prebuild Copy Section

Configure the native application in vite.config.ts, then generate the React Native community projects with one prebuild:

one({
  native: {
    app: {
      name: 'MyApp',
      icon: {
        source: './public/app-icon.png',
        backgroundColor: '#000000',
      },
      splash: {
        source: './public/splash.png',
        backgroundColor: '#000000',
        width: 200,
      },
      ios: {
        bundleId: 'com.example.myapp',
        usesNonExemptEncryption: false,
        fileSharing: true,
      },
      android: { applicationId: 'com.example.myapp' },
      imagePicker: {
        camera: 'Take profile photos.',
      },
    },
  },
})

One reads this manifest directly. It generates the iOS and Android app icons
and launch screens from the shared sources. imagePicker.camera is the iOS camera usage description; prebuild
writes it to NSCameraUsageDescription and declares the Android camera permission,
both required for One.ImagePicker.launchCamera. The icon must be a square image at least 1024 pixels wide. Splash
artwork is centered at width points on iOS and density-independent pixels on
Android. One removes a solid outer border matching backgroundColor before sizing
the artwork, then generates density-specific Android assets inside a 288 dp square. The launch screen
stays up until React Native draws its first content, so it never gives way to an
empty root.

ios.fileSharing sets UIFileSharingEnabled plus
LSSupportsOpeningDocumentsInPlace in the generated Info.plist. The user sees
the app's Documents as a folder in the Files app and in document pickers under
On My iPhone, and files the app saves there can be opened in place.

App appearance, links and store settings Copy Section

The rest of native.app covers appearance, links, and store settings:

• orientation: portrait, landscape or default (all four). Unset keeps a
  portrait-only phone.
• userInterfaceStyle: light or dark locks the appearance; automatic,
  like unset, follows the system.
• splash.resizeMode: cover fills the iOS launch screen with untrimmed
  artwork; contain (the default) centers it at width.
• splash.dark: backgroundColor, and optionally source and
  backgroundImage, for a launch in dark appearance.
• splash.backgroundImage: a full-bleed image, such as a gradient, under the
  artwork on the launch screen: iOS aspect-fills it, Android stretches it to
  fill (a gradient renders the same either way). Android's system splash
  itself shows only the color and icon.
• The launch screen stays up until the first screen draws. To reveal the app
  later (after a cache loads), call One.LaunchScreen.preventAutoHide() while
  modules evaluate and One.LaunchScreen.hide({ fade: true }) when ready.
• notifications.apsEnvironment: production for a build signed for
  TestFlight or the App Store; push uses development otherwise.
• ios.accentColor: { light, dark } hex colors for the app's tint (tab
  selection, text cursor, system controls), read in JS as
  PlatformColor('AccentColor').
• fonts: project-relative .ttf or .otf files bundled into the app. iOS
  lists them in UIAppFonts; Android loads them from assets/fonts. Use the
  font's own family name in styles.
• android.adaptiveIcon: foreground, then background (an image) or
  backgroundColor, and an optional monochrome layer for Android 13 themed
  icons. The foreground is a 108 dp square with the artwork inside the central
  66 dp.
• ios.associatedDomains (such as applinks:example.com) and
  android.appLinks ({ host, pathPrefix }, verified with autoVerify) route
  https links into the app.
• ios.usesAppleSignIn adds the Sign in with Apple entitlement.
• android.permissions adds manifest permissions (a bare name means
  android.permission.<name>); android.blockedPermissions removes ones a
  library merges in.
• android.targetSdk and android.compileSdk set the Gradle SDK levels.
• ios.googleServicesFile and android.googleServicesFile bundle a Firebase
  GoogleService-Info.plist and google-services.json; Android also gets the
  google-services Gradle plugin. For Google Sign-In, add the plist's
  REVERSED_CLIENT_ID to scheme.
• android.minify runs R8 on release builds, android.shrinkResources (which
  needs minify) drops unused resources, and android.proguardRules appends
  keep rules to proguard-rules.pro.
• ios.infoPlist and ios.entitlements add keys native.app does not model,
  such as NSUserTrackingUsageDescription. A key the template or another field
  already writes fails prebuild; set it through that field.

iOS widgets and Live Activities Copy Section

Set ios.widgets to have one prebuild --platform ios generate a WidgetKit extension,
App Group entitlements for both targets, and a small SwiftUI widget and Live Activity.
The app writes a typed payload to the App Group. The extension reads that payload
without running the app's JavaScript.

ios: {
  bundleId: 'com.example.myapp',
  deploymentTarget: '17.0',
  widgets: {
    appGroup: 'group.com.example.myapp',
    kind: 'MyAppStatus',
    displayName: 'My status',
    description: 'Shows the latest status.',
  },
}

import { One } from 'one'

await One.Widgets.write({ title: 'Order', value: '2 of 3', subtitle: 'On the way' })
const id = await One.LiveActivities.start('Order', { status: 'Preparing', value: '1 of 3' })
await One.LiveActivities.update(id, { status: 'On the way', value: '2 of 3' })
const token = await One.LiveActivities.pushToken(id)
const unsubscribe = One.LiveActivities.onPushToken(({ id, token }) => {
  // send the ActivityKit token to your server
})
await One.LiveActivities.end(id)
unsubscribe()

Pass true as the third argument to start to request an ActivityKit push token.
Set ios.widgets.pushNotifications: true before prebuild to add the APNs
entitlement; the signing profile must also enable Push Notifications.
If notifications.push is already enabled, One includes that entitlement in
the same app entitlement file as the widget's App Group.
pushToken returns the current token or null while iOS has not issued one;
onPushToken reports later token changes. These APIs are separate from notification
permissions and device tokens. App Groups and Live Activities need the corresponding
capabilities in the app's signing profile on a physical device.

One also accepts JSX layouts through One.iOS.WidgetUI. The app serializes the
layout to the same typed App Group contract or ActivityKit state. The generated
SwiftUI extension renders it without a JavaScript runtime or an extra package.

import { One } from 'one'

const W = One.iOS.WidgetUI

function OrderStatus({ progress, step }: { progress: string; step: number }) {
  return (
    <W.VStack style={{ padding: 12, spacing: 8 }}>
      <W.HStack>
        <W.Image systemName="shippingbox.fill" style={{ color: '#1685B1' }} />
        <W.Text style={{ fontSize: 18, fontWeight: 'bold' }}>Order</W.Text>
      </W.HStack>
      <W.Text>{progress}</W.Text>
      <W.Progress value={step} total={3} style={{ color: '#1685B1' }} />
    </W.VStack>
  )
}

await One.Widgets.writeView(<OrderStatus progress="2 of 3" step={2} />)
const id = await One.LiveActivities.startView('Order', {
  lockScreen: <OrderStatus progress="1 of 3" step={1} />,
  compactLeading: <W.Text>Order</W.Text>,
  compactTrailing: <W.Text>1/3</W.Text>,
  expandedBottom: <OrderStatus progress="1 of 3" step={1} />,
})
await One.LiveActivities.updateView(id, {
  lockScreen: <OrderStatus progress="2 of 3" step={2} />,
  compactLeading: <W.Text>Order</W.Text>,
  compactTrailing: <W.Text>2/3</W.Text>,
  expandedBottom: <OrderStatus progress="2 of 3" step={2} />,
})
await One.LiveActivities.end(id)

The activity view also accepts expandedLeading, expandedTrailing, and
expandedBottom for the expanded Dynamic Island. The compact slots and
minimal cover its other presentations.

WidgetUI supports Text, Image (SF Symbols), VStack, HStack,
ZStack, Spacer, Divider, Progress, Gauge, Circle, Rectangle,
RoundedRectangle, and Link. Styles include color, background color, font size,
weight and design, padding, corner radius, spacing, size, opacity, line limit,
and alignment. Colors use six-digit hex values. JSX layouts can contain pure
function components; compute hook state in the app and pass it as props. The
write and writeView methods update the same widget. Android widgets require
a separate Glance target, storage contract, and lifecycle; this setting
generates only iOS targets.

iOS Project Setup Copy Section

In the "Bundle React Native code and images" phase, make the following change in the shell script:

# ⬇️ Add this line directly above the line that calls react-native-xcode.sh
export CLI_PATH="$("$NODE_BINARY" --print "require('path').dirname(require.resolve('react-native/package.json')) + '/cli.js'")"

`"$NODE_BINARY" --print "require('path').dirname(require.resolve('react-native/package.json')) + '/scripts/react-native-xcode.sh'"`

Troubleshooting Copy Chapter

`ios/*.xcworkspace` isn't there Copy Section

Try cd ios && pod install && cd ...

Error: `node: No such file or directory` during Xcode build Copy Section

This often comes with Node found at: /private/var/folders/.../T/xfs-.../node and then /private/var/folders/.../T/xfs-.../node: No such file or directory.

Try to delete ios/.xcode.env.local.

Error: `No Metro config found` Copy Section

1. Make sure there's a react-native.config.cjs in your project which contains something like this:

   js Copy

   module.exports = require('one/react-native-config')

2. Confirm native.app.ios.bundleId is set in vite.config.ts.

3. Delete the generated ios directory and run one prebuild again.

Apps Onestack.Dev Data Docs Guides Isr (`apps/onestack.dev/data/docs/guides-isr.mdx`) Copy Section

title: Incremental Static Regeneration (ISR) Copy Chapter

Incremental Static Regeneration (ISR) lets you serve SSR pages with static-like performance by caching them at the CDN edge. Pages are generated on the first request, cached, then served instantly to subsequent visitors while being regenerated in the background.

How ISR Works Copy Chapter

ISR uses HTTP cache headers to tell CDNs when to cache and when to revalidate:

1. First visitor requests a page → SSR renders it → CDN caches the result
2. Subsequent visitors get the cached version instantly
3. After the cache expires, the next visitor still gets the cached version while the CDN fetches a fresh one in the background
4. Once regenerated, the new version replaces the cached one

No one ever waits for rendering - the CDN always serves something immediately.

Setting Up ISR Copy Chapter

Use setResponseHeaders in your SSR loader to set cache headers:

import { setResponseHeaders, useLoader } from 'one'

export async function loader({ params }) {
  // Set ISR cache headers
  await setResponseHeaders((headers) => {
    headers.set('Cache-Control', 'public, s-maxage=3600, stale-while-revalidate=86400')
  })

  const post = await fetchPost(params.slug)
  return { post }
}

export default function BlogPost() {
  const { post } = useLoader(loader)
  return <article>{post.content}</article>
}

Cache Header Patterns Copy Chapter

Basic ISR (1 hour cache, 1 day stale) Copy Section

headers.set('Cache-Control', 'public, s-maxage=3600, stale-while-revalidate=86400')

• public - Allow CDN caching
• s-maxage=3600 - CDN caches for 1 hour (3600 seconds)
• stale-while-revalidate=86400 - Serve stale content for up to 1 day while revalidating

Aggressive caching (1 day cache) Copy Section

For content that rarely changes:

headers.set('Cache-Control', 'public, s-maxage=86400, stale-while-revalidate=604800')

Short cache (5 minutes) Copy Section

For frequently updated content:

headers.set('Cache-Control', 'public, s-maxage=300, stale-while-revalidate=3600')

No caching (dynamic) Copy Section

For user-specific or real-time content:

headers.set('Cache-Control', 'private, no-store')

Conditional Caching Copy Chapter

Cache public pages, skip for authenticated users:

export async function loader({ request }) {
  const cookies = request?.headers.get('Cookie') || ''
  const isAuthenticated = cookies.includes('session=')

  if (isAuthenticated) {
    // Don't cache user-specific content
    await setResponseHeaders((headers) => {
      headers.set('Cache-Control', 'private, no-store')
    })
    return { user: await getUser(cookies) }
  }

  // Cache the public version
  await setResponseHeaders((headers) => {
    headers.set('Cache-Control', 'public, s-maxage=3600, stale-while-revalidate=86400')
  })
  return { user: null }
}

API Routes Copy Chapter

For API routes, set headers directly on the Response:

export async function GET(request: Request) {
  const posts = await fetchPosts()

  return new Response(JSON.stringify(posts), {
    headers: {
      'Content-Type': 'application/json',
      'Cache-Control': 'public, s-maxage=300, stale-while-revalidate=3600',
    },
  })
}

CDN Compatibility Copy Chapter

ISR requires a CDN that supports stale-while-revalidate:

For Cloudflare, use s-maxage only - pages will be fully regenerated after cache expires rather than served stale during revalidation.

When to Use ISR vs SSG vs SSR Copy Chapter

Use ISR when: Copy Section

• Content updates periodically but doesn't need instant updates
• You have many pages that can't all be pre-built (e.g., large blog, product catalog)
• You want SSR flexibility with near-static performance

Use SSG when: Copy Section

• Content is known at build time
• Updates can wait for a rebuild
• You want zero runtime cost

Use SSR (no cache) when: Copy Section

• Content is user-specific
• Data must be real-time
• Content varies per request (A/B tests, geolocation)

Example: Blog with ISR Copy Chapter

import { setResponseHeaders, useLoader } from 'one'
import { getPost } from '../lib/posts'

export async function loader({ params }) {
  const post = await getPost(params.slug)

  if (!post) {
    throw new Response('Not Found', { status: 404 })
  }

  // Cache for 1 hour, serve stale for up to 1 week
  await setResponseHeaders((headers) => {
    headers.set('Cache-Control', 'public, s-maxage=3600, stale-while-revalidate=604800')
  })

  return { post }
}

export default function BlogPost() {
  const { post } = useLoader(loader)

  return (
    <article>
      <h1>{post.title}</h1>
      <time>{post.date}</time>
      <div>{post.content}</div>
    </article>
  )
}

First visitor to /blog/my-post triggers SSR. The CDN caches the result. For the next hour, all visitors get the cached version instantly. After an hour, the next visitor still gets the cached version while the CDN regenerates in the background.

Apps Onestack.Dev Data Docs Guides Loader Redirects (`apps/onestack.dev/data/docs/guides-loader-redirects.mdx`) Copy Section

title: Loader Redirects Copy Chapter

Loader redirects let you protect routes server-side on both web and native. When a loader calls redirect(), unauthorized users are redirected before any sensitive data or page content reaches the client — for direct page loads, client-side <Link> navigation, and React Native navigation.

Basic Usage Copy Chapter

Use the redirect() helper in a loader to guard a route. Use +ssr so the loader runs on every request:

import { redirect, useLoader } from 'one'
import type { LoaderProps } from 'one'

export async function loader({ request }: LoaderProps) {
  const session = await getSession(request)

  if (!session) {
    throw redirect('/login')
  }

  return { user: session.user }
}

export default function Dashboard() {
  const { user } = useLoader(loader)
  return <Text>Welcome, {user.name}</Text>
}

Both throw redirect() and return redirect() work. throw is often cleaner since it stops execution immediately.

How It Works Copy Chapter

Direct Page Load Copy Section

When a user navigates directly to a protected URL (typing it in, refreshing, or following an external link), the loader runs on the server. If it calls redirect(), the server returns a standard HTTP 302 response and the browser redirects to the target page. The protected page never renders.

Client-Side Navigation Copy Section

When a user clicks a <Link> to a protected route, the behavior is more nuanced. Loaders run on the server, and the client fetches the result as a JavaScript module. Without special handling, the browser's module loader would silently follow a raw 302, try to parse the HTML login page as JavaScript, and fail.

One handles this differently:

1. The server detects the redirect response from the loader
2. Instead of returning a raw HTTP 302, it transforms the response into a JS module containing only redirect metadata — something like { __oneRedirect: "/login", __oneRedirectStatus: 302 }
3. The client receives this module and detects the redirect signal before navigating or rendering anything
4. The client navigates to the redirect target using a REPLACE action

The protected page never appears. No loader data, no component JavaScript output, no flash of unauthorized content. The server only sends back the redirect path.

React Native Copy Section

On native, loaders are fetched from the dev/production server and evaluated on the device. The same redirect mechanism applies:

1. The native app fetches the loader JavaScript from the server
2. The server runs the loader, detects the redirect, and transforms it into a module with redirect metadata
3. The native client detects the __oneRedirect signal after evaluating the loader
4. The router performs a replace navigation to the redirect target

The component never renders with protected data. This works for both <Link> navigation and programmatic navigation via router.push() / router.navigate().

Protecting Multiple Routes Copy Chapter

Use a shared auth helper to keep loaders clean:

import { redirect } from 'one'
import type { LoaderProps } from 'one'

export async function requireAuth(request: LoaderProps['request']) {
  const session = await getSession(request)

  if (!session) {
    throw redirect('/login')
  }

  return session
}

import { useLoader } from 'one'
import { requireAuth } from '~/features/auth/server'

export async function loader({ request }) {
  const session = await requireAuth(request)
  return { user: session.user }
}

export default function Dashboard() {
  const { user } = useLoader(loader)
  return <Text>Welcome, {user.name}</Text>
}

import { useLoader } from 'one'
import { requireAuth } from '~/features/auth/server'

export async function loader({ request }) {
  const session = await requireAuth(request)
  const prefs = await getUserPreferences(session.userId)
  return { prefs }
}

export default function Settings() {
  const { prefs } = useLoader(loader)
  return <PreferencesForm defaults={prefs} />
}

Redirect Status Codes Copy Chapter

The redirect() helper accepts an optional status code:

import { redirect } from 'one'

// 302 (default) - temporary redirect
throw redirect('/login')

// 301 - permanent redirect
throw redirect('/new-path', 301)

// 307 - temporary redirect, preserves HTTP method
throw redirect('/login', 307)

For auth guards, the default 302 is usually what you want. Use 307 if you need to preserve the original HTTP method (e.g., a POST request should remain a POST after redirect).

SSR vs SSG Routes Copy Chapter

Loader redirects work best with +ssr routes because the loader runs on every request with access to the request object (cookies, headers, etc.):

For protected routes, always use +ssr so auth is checked on every navigation.

When an SSG route redirects at build time, One generates a static redirect file. If a runtime server is present in production, it re-evaluates the loader per-request — so authenticated users see the real page while unauthenticated users get redirected.

What Gets Protected Copy Chapter

Loader redirects protect data. When a redirect fires:

• The loader data is never sent to the client
• The page component never renders on the server for that request
• The client receives only the redirect target path

Component JavaScript is always downloadable (this is true in every framework). Loaders protect the sensitive data your components would display — user profiles, account details, admin data, etc.

Loader Redirects vs Other Approaches Copy Chapter

You can combine these approaches. For example, use loader redirects to protect data on SSR routes, and `` to hide those routes from the tab bar on native.

Related Copy Chapter

• redirect - API reference for the redirect helper
• Loaders - Full loader documentation
• Authentication - Complete authentication patterns
• Middlewares - Server-side request interception
• Protected - Declarative route protection component

Apps Onestack.Dev Data Docs Guides Mdx (`apps/onestack.dev/data/docs/guides-mdx.mdx`) Copy Section

title: MDX Guide Copy Chapter

In building out this beautiful website, and the equally beautiful tamagui.dev, one of the trickier
parts was getting MDX to work well.

Since many blogs, apps, and documentation sites want to display Markdown content, we figured a guide showing how
we did it will be useful.

The @vxrn/mdx package bundles together Rehype plugins alongside mdx-bundler to provide a batteries-included MDX experience with:

• Syntax highlighting via refractor
• GitHub Flavored Markdown support
• Smart typography via remark-smartypants (with code blocks properly preserved)
• Auto-linked headings with slugified IDs
• Image metadata extraction including blur placeholders
• Reading time calculation
• Frontmatter with heading extraction for table of contents

Setting up your data dir Copy Section

The first step is to create a directory for your mdx files to live:

<RouteTree
routes={[
{ name: 'data', children: [
{ name: 'hello-world.mdx', description: 'Your MDX content goes here' },
] },
]}
/>

Throw some stuff in that file:

---
title: MDX Guide
description: Setting up MDX for web
---

In building out this beautiful website, and the equally beautiful [tamagui.dev](https://tamagui.dev), the surprising
most difficult part was getting MDX to work well...

Setting up `@vxrn/mdx` Copy Section

Next, we add our mdx dependencies:

yarn add @vxrn/mdx mdx-bundler

We set up our MDX components (using Tamagui in this example):

import { Text } from "react-native";

export const components = {
  h1: ({ children }) => (
    <Text style={{ fontSize: 24, fontWeight: "bold", marginBottom: 10 }}>
      {children}
    </Text>
  ),
  h2: ({ children }) => (
    <Text style={{ fontSize: 20, fontWeight: "bold", marginBottom: 8 }}>
      {children}
    </Text>
  ),
  h3: ({ children }) => (
    <Text style={{ fontSize: 18, fontWeight: "bold", marginBottom: 6 }}>
      {children}
    </Text>
  ),
  p: ({ children }) => <Text style={{ marginBottom: 10 }}>{children}</Text>,
};

And then all we need is a new route:

import { getMDXComponent } from "mdx-bundler/client";
import { useMemo } from "react";
import { useLoader } from "one";
import { Text, View } from "react-native";
import { components } from "~/features/MDXComponents";

export async function generateStaticParams() {
  const { getAllFrontmatter } = await import("@vxrn/mdx");
  const frontmatters = getAllFrontmatter("data");
  const paths = frontmatters.map(({ slug }) => ({
    slug: slug.replace(/.*docs\//, ""),
  }));
  return paths;
}

export async function loader({ params }) {
  const { getMDXBySlug } = await import("@vxrn/mdx");
  const { frontmatter, code } = await getMDXBySlug("data", params.slug);
  return {
    frontmatter,
    code,
  };
}

export function DocsPage() {
  const { code, frontmatter } = useLoader(loader);
  const Component = useMemo(() => getMDXComponent(code), [code]);

  return (
    <View style={{ padding: 20 }}>
      <Text style={{ fontSize: 48, fontWeight: "bold", marginBottom: 10 }}>
        {frontmatter.title}
      </Text>
      <Component components={components} />
    </View>
  );
}

Note that we await import the @vxrn/mdx library - this is because One by default builds out your server
and API routes to CommonJS, but some of the rehype/remak dependencies are ESM. Long story short - this makes it work.

Configuring Vite for MDX Support Copy Section

To ensure that MDX works correctly with your One project, you'll need to configure Vite. Update your vite.config.ts file with the following content:

import { defineConfig } from 'vite'
import { one } from 'one/vite'

export default defineConfig({
  ssr: {
    noExternal: true,
    external: ['@vxrn/mdx'],
  },
  plugins: [
    one({
      web: {
        defaultRenderMode: 'ssg',
      },
    }),
  ],
})

This configuration does a few important things:

1. It sets noExternal: true in the SSR options, which tells Vite to bundle all dependencies for server-side rendering.
2. It explicitly marks @vxrn/mdx as an external dependency, which is necessary because it contains ESM modules that shouldn't be bundled.

That should do it. We say should, because there's a lot going on here, and many sub-deps inside @vxrn/mdx that need to work together. Let us know if this works for you!

Apps Onestack.Dev Data Docs Guides Migrating Create React App Cra To Vite With One (`apps/onestack.dev/data/docs/guides-migrating-create-react-app-cra-to-vite-with-one.mdx`) Copy Section

title: Migrate from Create React App (CRA) to Vite with One Copy Chapter

Migrating from Create React App (CRA) to One is easy. In this guide we'll use the default CRA output and show how you can move over to One.

One is a React framework for web, iOS, and Android, built on the power of Vite - it's actually just a single Vite plugin. One saves you a lot of complexity when moving from CRA, it offers faster build times, built-in TypeScript support, SPA or server rendering, file system routes, and seamless cross-platform development capabilities.

Let's walk through the migration process step by step.

Step 1: Add One to Your Project Copy Section

First, let's add One and its dependencies to your project:

yarn add one

Step 2: Update Your Project Structure Copy Section

One uses a file-based routing system, which means we need to adjust our project structure slightly. Here's what we'll do:

<RouteTree
routes={[
{ name: 'package.json' },
{ name: 'vite.config.ts', add: true, highlight: true, description: 'Add a vite.config.ts file to configure our build system.'},
{ name: 'public', children: [
{ name: 'favicon.ico' },
{ name: 'index.html', delete: true, description: 'Remove index.html as One will handle app rendering.' },
] },
{ name: 'app', add: true, description: 'Add an app directory for our file system routes.', children: [
{ name: 'index.tsx', add: true, highlight: true, description: 'Move and rename App.js to index.tsx.' },
] },
{ name: 'src', children: [
{ name: 'App.css' },
{ name: 'App.js', delete: true, description: 'Move App.js content to app/index.tsx.' },
{ name: 'App.test.js' },
{ name: 'index.css' },
{ name: 'index.js', delete: true, description:'Remove index.js. One's file system router replaces this.' },
{ name: 'reportWebVitals.js', delete: true, description: 'Remove reportWebVitals.js.' },
{ name: 'setupTests.js', delete: true, description: 'Remove setupTests.js. We'll use Vitest for testing.' }
] }
]}
/>

Step 3: Configure Vite Copy Section

Create a new vite.config.ts file in your project root with the following content:

import type { UserConfig } from 'vite'
import { one } from 'one/vite'

export default {
  plugins: [
    one({
      web: {
        defaultRenderMode: 'spa'
      }
    }),
  ],
} satisfies UserConfig

This minimal configuration sets up One with Vite, enabling all the goodness that comes with it. Note that we're setting defaultRenderMode to 'spa' (Single Page App) for compatibility with Create React App. This ensures that your app behaves similarly to how it did with CRA, rendering entirely on the client side.

The 'spa' mode is the simplest strategy, where your app is not rendered on the server at all. Instead, only the JavaScript to render your page is served to the user's browser. This avoids some of the complexity associated with server-side rendering, making it a good starting point for migrating from CRA.

If you want to explore other rendering modes later, such as Static Site Generation (SSG) or Server-Side Rendering (SSR), you can change this setting. Each mode has its own trade-offs in terms of performance, SEO, and complexity. For more information on the available render modes and their implications, refer to the One configuration documentation.

Step 4: Update package.json Scripts Copy Section

Let's update our package.json scripts to use One's commands:

{
  "scripts": {
    "start": "one dev",
    "build": "one build",
    "test": "vitest run"
  }
}

These new scripts replace the CRA equivalents, giving you access to One's optimized development and build processes.

Step 5: Update Your Main Component Copy Section

Now, let's update our main component. We'll move src/App.js to app/index.tsx and make a few adjustments:

import '~/src/App.css'
import logo from '~/src/logo.svg'

export default function App() {
  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>
          Edit <code>app/index.tsx</code> and save to reload.
        </p>
        <a
          className="App-link"
          href="https://reactjs.org"
          target="_blank"
          rel="noopener noreferrer"
        >
          Learn React
        </a>
      </header>
    </div>
  )
}

Notice how we've updated the import paths using the ~ alias. One supports tsconfig by default, and will also add a tsconfig.json file if you don't have one already, with the ~ path alias configured. Of course, you can change this to suit your needs.

Step 6: Remove Unnecessary Files Copy Section

You can now safely remove the following files:

• public/index.html
• src/index.js
• src/reportWebVitals.js
• src/setupTests.js

One handles app rendering and provides its own optimized setup for these functionalities.

Step 7: Run Your Migrated App Copy Section

You're all set! Now you can start your newly migrated One app:

yarn start

Visit http://localhost:8081 to see your app in action. Use the --port flag if you need to change the port.

Next Steps Copy Chapter

Congratulations! You've successfully migrated from Create React App to One. Here are some next steps to consider:

1. Explore One's features: Check out the One documentation to learn about its powerful features like SSR, file-based routing, and more.

2. Optimize for production: One provides excellent production optimizations out of the box. Run yarn build to create an optimized production build.

3. Add Tamagui: For a powerful, fully type-safe UI kit that works seamlessly with One, consider adding Tamagui. It provides SSR-safe styling, animations, and themes.

4. Implement dark mode: One makes it easy to add SSR-safe dark mode. Check out our Dark Mode guide for a quick setup.

Apps Onestack.Dev Data Docs Guides Open Graph (`apps/onestack.dev/data/docs/guides-open-graph.mdx`) Copy Section

title: Dynamic OpenGraph Images Copy Chapter

OpenGraph images are the preview images that appear when you share a link on social media. One supports dynamic OG image generation using API routes and the @vercel/og library.

Setup Copy Chapter

Install the @vercel/og package:

npm install @vercel/og

Basic API Route Copy Chapter

Create an API route that generates images dynamically:

import { ImageResponse } from '@vercel/og'

export const GET = async (request: Request) => {
  const url = new URL(request.url)
  const title = url.searchParams.get('title') || 'One Framework'

  return new ImageResponse(
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        alignItems: 'center',
        justifyContent: 'center',
        width: '100%',
        height: '100%',
        backgroundColor: '#000',
        color: '#fff',
        fontSize: 60,
        fontWeight: 700,
      }}
    >
      {title}
    </div>,
    {
      width: 1200,
      height: 630,
    }
  )
}

This creates an endpoint at /api/og that generates PNG images on the fly.

Using in Pages Copy Chapter

Reference the dynamic image in your page's meta tags:

import { Head, useParams } from 'one'

export default function BlogPost() {
  const { slug } = useParams()
  const title = 'My Blog Post'
  const ogUrl = `/api/og?title=${encodeURIComponent(title)}`

  return (
    <>
      <Head>
        <meta property="og:image" content={ogUrl} />
        <meta property="og:image:width" content="1200" />
        <meta property="og:image:height" content="630" />
        <meta name="twitter:card" content="summary_large_image" />
        <meta name="twitter:image" content={ogUrl} />
      </Head>
      {/* page content */}
    </>
  )
}

Custom Fonts Copy Chapter

Load custom fonts for better typography:

import { ImageResponse } from '@vercel/og'
import { readFile } from 'fs/promises'
import { join } from 'path'

// Load font once at module level
const interBold = readFile(join(process.cwd(), 'public/fonts/Inter-Bold.ttf'))

export const GET = async (request: Request) => {
  const url = new URL(request.url)
  const title = url.searchParams.get('title') || 'One Framework'

  return new ImageResponse(
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        alignItems: 'center',
        justifyContent: 'center',
        width: '100%',
        height: '100%',
        backgroundColor: '#000',
        color: '#fff',
        fontFamily: 'Inter',
        fontSize: 60,
      }}
    >
      {title}
    </div>,
    {
      width: 1200,
      height: 630,
      fonts: [
        {
          name: 'Inter',
          data: await interBold,
          weight: 700,
        },
      ],
    }
  )
}

With Background Images Copy Chapter

Include images in your OG graphics:

import { ImageResponse } from '@vercel/og'
import { readFile } from 'fs/promises'
import { join } from 'path'

export const GET = async (request: Request) => {
  const url = new URL(request.url)
  const title = url.searchParams.get('title') || 'One Framework'

  // Read local image as base64
  const bgImage = await readFile(join(process.cwd(), 'public/og-background.png'))
  const bgBase64 = `data:image/png;base64,${bgImage.toString('base64')}`

  return new ImageResponse(
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        alignItems: 'center',
        justifyContent: 'center',
        width: '100%',
        height: '100%',
        backgroundImage: `url(${bgBase64})`,
        backgroundSize: 'cover',
      }}
    >
      <div
        style={{
          fontSize: 60,
          fontWeight: 700,
          color: '#fff',
          textShadow: '0 2px 10px rgba(0,0,0,0.5)',
        }}
      >
        {title}
      </div>
    </div>,
    { width: 1200, height: 630 }
  )
}

Helper Function Copy Chapter

Create a utility to generate OG URLs consistently:

import { getURL } from 'one'

type OgParams = {
  title: string
  type?: 'blog' | 'docs' | 'default'
  author?: string
  section?: string
}

export function ogUrl(params: OgParams): string {
  const base = getURL()
  const search = new URLSearchParams()

  Object.entries(params).forEach(([key, value]) => {
    if (value) search.set(key, value)
  })

  return `${base}/api/og?${search.toString()}`
}

Use it in pages:

import { ogUrl } from '~/features/og'

const imageUrl = ogUrl({
  title: 'My Blog Post',
  type: 'blog',
  author: 'Jane Doe',
})

Caching Copy Chapter

Add cache headers for better performance:

import { ImageResponse } from '@vercel/og'
import { setResponseHeaders } from 'one'

export const GET = async (request: Request) => {
  // Cache for 1 day on CDN, 1 week stale-while-revalidate
  await setResponseHeaders((headers) => {
    headers.set('Cache-Control', 'public, s-maxage=86400, stale-while-revalidate=604800')
  })

  const url = new URL(request.url)
  const title = url.searchParams.get('title') || 'One Framework'

  return new ImageResponse(
    <div
      style={{
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
        width: '100%',
        height: '100%',
        backgroundColor: '#000',
        color: '#fff',
        fontSize: 60,
      }}
    >
      {title}
    </div>,
    { width: 1200, height: 630 }
  )
}

Debugging Copy Chapter

Test your OG images directly in the browser:

http://localhost:8081/api/og?title=Test+Title

Use the OpenGraph debugger or social platform preview tools to verify how images appear when shared.

Apps Onestack.Dev Data Docs Guides Ota Updates (`apps/onestack.dev/data/docs/guides-ota-updates.mdx`) Copy Section

title: Over-the-air Updates Copy Chapter

Over-the-air (OTA) updates ship JavaScript and asset changes to installed native apps without going through TestFlight or the Play Store.

One.Updates Copy Chapter

One ships its own OTA client. Set the update url and runtime version in native.app:

one({
  native: {
    app: {
      // ...
      updates: {
        url: 'https://updates.example.com',
        runtimeVersion: '1.0',
      },
    },
  },
})

Prebuild stamps both into the binary. Publish from the app's source and serve the output directory at //<runtimeVersion>/:

one updates publish --platform ios --out ./ota-out
one updates publish --platform android --out ./ota-out-android

The launcher picks the newest downloaded update for the binary's runtime version before React Native starts, and rolls back when an update fails before first render. See Updates for the client API and publish options.

hot-updater Copy Chapter

hot-updater is a self-hosted alternative (Supabase, Cloudflare R2, S3, custom). Install and init:

bun add @hot-updater/react-native react-native-mmkv
bun add -D hot-updater @hot-updater/bare @hot-updater/supabase
npx hot-updater init

Wrap your app:

import { HotUpdater } from '@hot-updater/react-native'

export default HotUpdater.wrap({
  source: process.env.ONE_PUBLIC_HOT_UPDATER_URL,
})(App)

Publish:

npx hot-updater deploy -p ios -c production
npx hot-updater deploy -p android -c production

See hot-updater.dev/docs for full backend setup. Apps on EAS Update follow Coming from Expo.

What's OTA-safe Copy Chapter

Only publish OTA updates for changes that don't touch the native binary:

• ✅ JavaScript, TypeScript, JSX, styles, copy, bundled assets
• ❌ native dependencies, native.app fields that affect native output, any native iOS/Android file

For those, bump runtimeVersion, build a fresh TestFlight/Play binary, and only then publish OTA updates against the new runtime. The runtime version gates delivery so devices on the old binary don't receive incompatible updates.

Owning the config files yourself Copy Chapter

If you'd rather commit babel.config.cjs / metro.config.cjs and customize them (custom Metro resolvers, watcher options, etc.), generate them once:

npx one metro-eject

This writes shim files (delegating to one/babel-preset and one/metro-config) without the @one/generated marker comment. After ejecting:

• The files are yours — edit freely and commit them.
• The CI postinstall hook detects the missing marker and won't touch them.
• You stay in charge of keeping them in sync with future One releases.

A typical ejected metro.config.cjs looks like:

const { withOne } = require('one/metro-config')
const oneBundlerOptions = {
  routerRoot: 'app',
}

module.exports = (async () => {
  const config = await withOne(__dirname, oneBundlerOptions)
  // your customizations here
  return config
})()

Pass --force to overwrite existing files.

Reference Copy Chapter

• Updates
• hot-updater documentation

Apps Onestack.Dev Data Docs Guides Skew Protection (`apps/onestack.dev/data/docs/guides-skew-protection.mdx`) Copy Section

title: Skew Protection Copy Chapter

After a deployment, users with open tabs still have old JavaScript bundles. When they navigate, dynamic imports reference chunk URLs that no longer exist on the server, causing 404s, broken UI, or blank pages.

One has built-in skew protection that detects these failures and recovers automatically.

Configuration Copy Chapter

import { one } from 'one/vite'

export default {
  plugins: [
    one({
      web: {
        skewProtection: true // true (default) | 'proactive' | false
      }
    })
  ]
}

Error Recovery (default) Copy Chapter

With skewProtection: true (the default), One detects chunk load failures and automatically reloads the page. This covers two failure paths:

• Vite preload errors — caught via the vite:preloadError event when Vite's module preloader fails to fetch a chunk
• Dynamic import errors — caught when One's own dynamicImport() calls fail with browser-specific chunk load error messages (Chrome, Firefox, Safari)

When a failure is detected, the page reloads so the browser fetches fresh HTML with the new asset URLs. A sessionStorage guard prevents infinite reload loops — if a reload already happened within the last 10 seconds, the guard stops further reloads.

No configuration needed. This is always on unless you explicitly set skewProtection: false.

Proactive Mode Copy Chapter

one({
  web: {
    skewProtection: 'proactive'
  }
})

Proactive mode adds version polling on top of error recovery. Instead of waiting for a chunk to fail, the client periodically checks whether a new version has been deployed and forces a full-page navigation on the next link click.

How it works Copy Section

1. At build time, One emits a version.json file containing the build's cache key
2. The client polls version.json every 2 minutes with cache-busting headers
3. When the polled version doesn't match the running bundle's version, the app is marked as stale
4. On the next client-side navigation, instead of doing an SPA transition, One does a full window.location.href navigation so the server returns fresh HTML with new assets

This is similar to how SvelteKit handles version skew. The user never sees a broken page — they just get a slightly slower (full-page) navigation that loads the new deployment.

Events Copy Section

When a version mismatch is detected, One dispatches a one-version-update custom event on window:

window.addEventListener('one-version-update', (e) => {
  const version = (e as CustomEvent<{ version?: string }>).detail.version
  console.log('new version available:', version)
  // show a toast, banner, etc.
})

You can use this to show users a "new version available" banner with a manual refresh button instead of waiting for the next navigation.

Window flag Copy Section

The window.__oneVersionStale flag is set to true when a version mismatch is detected. You can check this from anywhere in your app:

if ((window as any).__oneVersionStale) {
  // app has a newer deployment available
}

Resilient imports Copy Chapter

One also exports the helpers behind this recovery from 'one', for your own lazy boundaries and dynamic imports:

• lazyWithRetry(loader, options?): a drop-in replacement for React.lazy. It retries a transient chunk failure in place before React caches the result, so one failed fetch does not poison the component for the whole session.
• loadWithRetry(loader, options?): wraps any async loader with retry and backoff. On an unrecoverable chunk-load error it triggers the debounced reload instead of rejecting into a surviving tree.
• isChunkLoadError(err): returns true when the error matches a browser chunk-load failure message.
• handleSkewError(): schedules the debounced one-time reload. Returns true when a reload was scheduled, false on the server or when a reload already happened in the last 10 seconds.

import { Suspense } from 'react'
import { handleSkewError, isChunkLoadError, lazyWithRetry, loadWithRetry } from 'one'

// resilient lazy component: retries transient failures, reloads on deploy skew
const SettingsPage = lazyWithRetry(() => import('../components/SettingsPage'))

export function SettingsRoute() {
  return (
    <Suspense fallback={null}>
      <SettingsPage />
    </Suspense>
  )
}

// resilient data loader with custom retry budget
const stats = await loadWithRetry(() => fetch('/api/stats').then((res) => res.json()), {
  attempts: 5,
  delayMs: 1000,
})

// manual recovery in your own dynamic import
try {
  await import('../components/HeavyPanel')
} catch (err) {
  if (isChunkLoadError(err)) handleSkewError()
}

Disabling Copy Chapter

To turn off skew protection entirely:

one({
  web: {
    skewProtection: false
  }
})

This disables both the error recovery reload and the proactive polling. Chunk load failures will be silently swallowed as they were before this feature existed.

CDN Edge Caching Copy Chapter

With skew protection enabled, One automatically sets cache headers that allow CDN edge caching for SSG and SPA pages:

cache-control: public, s-maxage=60, stale-while-revalidate=120

This means:

• CDN caches pages for 60 seconds — subsequent requests are served from edge, cutting TTFB to ~50ms
• Stale-while-revalidate for 120 seconds — even after 60s, the CDN serves stale content while fetching fresh in the background
• SSR pages are not cached — they return no-cache since content is dynamic per request

Why this is safe Copy Section

Previously, CDN caching HTML was risky: after a deploy, cached HTML references old JS bundles that may not exist, causing 404s and broken pages.

Skew protection solves this. If a cached page tries to load a missing chunk:

1. The chunk request 404s
2. Skew protection detects the failure via vite:preloadError
3. The page auto-reloads, fetching fresh HTML from the origin
4. User sees the new deployment

The worst case is a brief flash on reload — much better than a broken page.

Overriding cache headers Copy Section

If you need custom cache behavior, set headers in your loader or middleware:

import { setResponseHeaders } from 'one'

export async function loader() {
  // cache for 5 minutes at the edge
  await setResponseHeaders((headers) => {
    headers.set('cache-control', 'public, s-maxage=300')
  })
  return { data: '...' }
}

Custom headers take precedence — One only sets defaults when no cache-control header is present.

Apps Onestack.Dev Data Docs Guides Tamagui (`apps/onestack.dev/data/docs/guides-tamagui.mdx`) Copy Section

title: Tamagui and One Copy Chapter

Tamagui and One go together so well you'd swear they were made by the same person. When targeting both native and web, and wanting to share UI, you don't have many options.

Tamagui does many things that no other universal libraries do: all of its features work with SSR without flashing of styles, it supports spring and CSS animations (also SSR safe), it supports light and dark mode (also SSR safe), it's fully type safe, it supports container queries, and it outputs nearly ideal code for each platform.

We're going to support SSR-safe light and dark mode with the @vxrn/color-scheme helpers that one re-exports:

npm add tamagui @tamagui/config @tamagui/vite-plugin

Be sure to check out the Dark mode guide for more detail there.

Add your config/tamagui.config.ts:

import { defaultConfig } from '@tamagui/config/v5'
import { animations } from '@tamagui/config/v5-css'
import { createTamagui } from 'tamagui'

export const config = createTamagui({
  ...defaultConfig,
  animations,
})

type Conf = typeof config

declare module 'tamagui' {
  interface TamaguiCustomConfig extends Conf {}
}

export default config

The reason we separate this file out is that it lets the Tamagui compiler optimize things. You don't have to do this, but it's pretty easy. The declare module block types your tokens and themes across the app.

This preset config we recommend as it lets you just get working on your app, but if you want a custom configuration, the Takeout starter in npx one has a nice custom configuration example.

Next, update your root _layout.tsx. one re-exports the @vxrn/color-scheme helpers, so SchemeProvider and useUserScheme come straight from one:

import type { ReactNode } from 'react'
import { SchemeProvider, Slot, useUserScheme } from 'one'
import { TamaguiProvider } from 'tamagui'
import config from '../config/tamagui.config'

export default function Layout() {
  return (
    <SchemeProvider>
      <ThemeProvider>
        <Slot />
      </ThemeProvider>
    </SchemeProvider>
  )
}

// this is in its own component so it can access the useUserScheme hook
const ThemeProvider = ({ children }: { children: ReactNode }) => {
  const userScheme = useUserScheme()
  return (
    <TamaguiProvider config={config} defaultTheme={userScheme.value}>
      {children}
    </TamaguiProvider>
  )
}

Next for the Vite plugin. You don't need to set up the Tamagui Vite plugin, but it adds a lot of nice stuff: debug attributes, broader react-native compatibility, and the optimizing compiler. The compiler runs for every component listed in components; pass disableExtraction: true to turn it off.

import { tamaguiPlugin } from '@tamagui/vite-plugin'
import { one } from 'one/vite'
import type { UserConfig } from 'vite'

export default {
  plugins: [
    one(),
    tamaguiPlugin({
      components: ['tamagui'],
      config: './config/tamagui.config.ts',
    }),
  ],
} satisfies UserConfig

Optimizing further Copy Section

If you want to optimize things a bit further, we can output the Tamagui design system CSS to a stylesheet by changing our plugin configuration:

import { tamaguiPlugin } from '@tamagui/vite-plugin'
import { one } from 'one/vite'
import type { UserConfig } from 'vite'

export default {
  plugins: [
    one(),
    tamaguiPlugin({
      components: ['tamagui'],
      config: './config/tamagui.config.ts',
      outputCSS: './public/tamagui.css',
    }),
  ],
} satisfies UserConfig

And then changing our root layout to add disableInjectCSS, and instead importing the CSS at the top:

import '../public/tamagui.css'

import type { ReactNode } from 'react'
import { SchemeProvider, Slot, useUserScheme } from 'one'
import { TamaguiProvider } from 'tamagui'
import config from '../config/tamagui.config'

export default function Layout() {
  return (
    <SchemeProvider>
      <ThemeProvider>
        <Slot />
      </ThemeProvider>
    </SchemeProvider>
  )
}

const ThemeProvider = ({ children }: { children: ReactNode }) => {
  const userScheme = useUserScheme()
  return (
    <TamaguiProvider config={config} defaultTheme={userScheme.value} disableInjectCSS>
      {children}
    </TamaguiProvider>
  )
}

That should be about it! You now have SSR safe styling, light and dark mode, and a bunch of advanced styling features.

Check out the Tamagui site for more documentation.

Apps Onestack.Dev Data Docs Guides (`apps/onestack.dev/data/docs/guides.mdx`) Copy Section

title: Guides Copy Chapter

Guides to common patterns are here. If you'd like to contribute a Guide, please do! Check with us in the Discord, then open a PR.

Apps Onestack.Dev Data Docs Helpers GetURL (`apps/onestack.dev/data/docs/helpers-getURL.mdx`) Copy Section

title: getURL Copy Chapter

A function that takes no arguments and returns a string of the current URL of the running application on client or server.

import { getURL } from 'one'

const url = getURL()
// Dev: "http://127.0.0.1:8081"
// Prod: Your ONE_SERVER_URL value

For example, in dev-mode by default this would be a string of http://127.0.0.1:8081. In non-development environments you will need to set process.env.ONE_SERVER_URL to your production URL with no trailing /.

Apps Onestack.Dev Data Docs Helpers Href (`apps/onestack.dev/data/docs/helpers-href.mdx`) Copy Section

title: href Copy Chapter

A simple function allows for creating typed route strings. It's a type-level only check, at runtime it only validates that it is a string.

import { href } from 'one'

const postPageLink = href(`/post/hello-world`) // will type error if invalid Href

This is useful for ensuring your links are valid routes in your application at compile time.

Apps Onestack.Dev Data Docs Helpers IsResponse (`apps/onestack.dev/data/docs/helpers-isResponse.mdx`) Copy Section

title: isResponse Copy Chapter

One uses Request/Response type objects for API routes, but for some environments doing an instanceof Response can fail.

isResponse takes any value and returns true if it is a Response-like object. Useful for API utility functions.

import { isResponse } from 'one'

export async function handleResult(result: unknown) {
  if (isResponse(result)) {
    return result
  }
  return Response.json(result)
}

Apps Onestack.Dev Data Docs Helpers Redirect (`apps/onestack.dev/data/docs/helpers-redirect.mdx`) Copy Section

title: redirect Copy Chapter

A function that takes two arguments: a string path, and an optional number status.

import { redirect } from 'one'

export function redirectToLogin() {
  return redirect('/login')
}

It accepts relative paths by using the getURL helper internally.

On the server (including in loaders) it returns a Response.redirect object. On the client it calls router.navigate and returns void.

Usage in Loaders Copy Chapter

Use redirect() in loaders to protect routes. When a user navigates via <Link>, the loader runs on the server and the redirect is detected on the client before the protected page ever renders — no flash of unauthorized content, no data leaks.

import { redirect, useLoader } from 'one'
import type { LoaderProps } from 'one'

export function loader({ request }: LoaderProps) {
  const session = getSession(request)

  if (!session) {
    throw redirect('/login')
  }

  return { user: session.user }
}

export default function Dashboard() {
  const { user } = useLoader(loader)
  return <Text>Welcome, {user.name}</Text>
}

Both throw redirect() and return redirect() work. throw is often cleaner since it stops execution immediately.

This works for both direct page loads (server returns a 302) and client-side <Link> navigation (server returns a redirect signal that the client intercepts before rendering).

How It Works Copy Section

During client-side navigation, loaders run on the server and the client fetches the result as a JavaScript module. When a loader returns redirect():

1. The server detects the redirect response
2. Instead of returning a raw HTTP 302 (which the browser's module loader would silently follow), the server transforms it into a JS module containing redirect metadata
3. The client detects the redirect signal before navigating or rendering anything
4. The client navigates to the redirect target using REPLACE — the protected page never appears

This means no sensitive data reaches the client when a redirect occurs. The server only sends back the redirect path.

Related Copy Chapter

• Loaders - Data loading for routes
• Authentication - Full authentication guide

Apps Onestack.Dev Data Docs Helpers ServerData (`apps/onestack.dev/data/docs/helpers-serverData.mdx`) Copy Section

title: setServerData / getServerData Copy Chapter

import { setServerData, getServerData } from 'one'

type SafeURLs = `${`https://tamagui.dev` | `http://localhost`}${string}

const useFetch = async (url: SafeURLs) => {
  if (process.env.VITE_ENVIRONMENT === 'ssr') {
    // on the server, fetch and store during render, then return directly:
    // getServerData throws on the server
    const data = await fetch(url).then(res => res.json())
    setServerData(url, data)
    return data
  }

  // on the client, read the data the server stored
  return getServerData(url)
}

export default async (props) => {
  const serverData = await useFetch(props.url)
  return <div />
}

// can use it in loaders, too

export const loader = async ({ params }) => {
  await doSomething()
  setServerData(params.id, 'data')
  return {}
}

import { setResponseHeaders } from 'one'

await setResponseHeaders((headers) => {
  headers.set('X-Custom-Header', 'value')
})

import { setResponseHeaders, useLoader } from 'one'

export async function loader({ params }) {
  await setResponseHeaders((headers) => {
    headers.set('Cache-Control', 'public, s-maxage=3600, stale-while-revalidate=86400')
  })

  const post = await fetchPost(params.slug)
  return { post }
}

export default function BlogPost() {
  const { post } = useLoader(loader)
  return <article>{post.content}</article>
}

import { setResponseHeaders } from 'one'

export async function POST(request: Request) {
  const { token } = await authenticateUser(request)

  await setResponseHeaders((headers) => {
    headers.append('Set-Cookie', `session=${token}; HttpOnly; Secure; SameSite=Strict; Path=/`)
  })

  return Response.json({ success: true })
}

import { createMiddleware, setResponseHeaders } from 'one'

export default createMiddleware(({ request }) => {
  setResponseHeaders((headers) => {
    headers.set('X-Request-Id', crypto.randomUUID())
  })
})

import { watchFile } from 'one'
import { readFile } from 'fs/promises'

export async function loader({ params: { slug } }) {
  const filePath = `./content/${slug}.mdx`
  watchFile(filePath)
  const content = await readFile(filePath, 'utf-8')
  return { content }
}

import { useActiveParams } from 'one'

export default function AnalyticsTracker() {
  const params = useActiveParams()

  useEffect(() => {
    analytics.track('page_view', params)
  }, [params])

  return null
}

// Stack: /home -> /users/123 -> /users/123/edit
// Current screen: /users/123/edit

// In /users/123 component (background):
useParams()        // { id: '123' } - no updates
useActiveParams()  // Updates on every navigation

// In /users/123/edit component (focused):
useParams()        // { id: '123' }
useActiveParams()  // { id: '123' }

import { useActiveParams, usePathname } from 'one'

function Breadcrumbs() {
  const pathname = usePathname()
  const params = useActiveParams<{ id?: string }>()

  // Always shows current route, even from a layout component
  return (
    <nav>
      <span>{pathname}</span>
      {params.id && <span> - ID: {params.id}</span>}
    </nav>
  )
}

import { useBlocker } from 'one'
import { useState } from 'react'

export default function EditPage() {
  const [isDirty, setIsDirty] = useState(false)
  const blocker = useBlocker(isDirty)

  return (
    <>
      <form onChange={() => setIsDirty(true)}>
        <input type="text" />
        <button type="submit">Save</button>
      </form>

      {blocker.state === 'blocked' && (
        <div className="modal">
          <p>You have unsaved changes. Leave anyway?</p>
          <button onClick={blocker.reset}>Stay</button>
          <button onClick={blocker.proceed}>Leave</button>
        </div>
      )}
    </>
  )
}

const blocker = useBlocker(({ currentLocation, nextLocation }) => {
  // Only block when leaving the /edit section
  return currentLocation.startsWith('/edit') && !nextLocation.startsWith('/edit')
})

if (blocker.state === 'unblocked') {
  // Normal state, navigation is allowed
}

if (blocker.state === 'blocked') {
  blocker.location  // The destination the user tried to navigate to
  blocker.reset()   // Cancel the navigation, stay on current page
  blocker.proceed() // Allow the navigation to continue
}

if (blocker.state === 'proceeding') {
  blocker.location  // Where we're navigating to
}

import type { Blocker, BlockerFunction, BlockerState } from 'one'

// BlockerState is 'unblocked' | 'blocked' | 'proceeding'

// BlockerFunction signature
type BlockerFunction = (args: {
  currentLocation: string
  nextLocation: string
  historyAction: 'push' | 'pop' | 'replace'
}) => boolean

/* Detailed source-code truncated for AI context efficiency. */

// app/_layout.tsx, works on both platforms
import { Drawer } from 'one/drawer'
import { Link, useDrawer } from 'one'

function WebDrawerLayout() {
  const { screens, focused, isOpen, close, toggle } = useDrawer()

  return (
    <>
      <button onClick={toggle}>Menu</button>

      {isOpen && (
        <nav>
          {screens.map((screen) => (
            <Link key={screen.key} href={screen.href} onPress={close}>
              {screen.options.drawerLabel ?? screen.options.title ?? screen.name}
            </Link>
          ))}
        </nav>
      )}

      {focused.element}
    </>
  )
}

export default function Layout() {
  return (
    <Drawer>
      <Drawer.Screen name="index" options={{ drawerLabel: 'Home' }} />
      <Drawer.Screen name="settings" options={{ drawerLabel: 'Settings' }} />
      <WebDrawerLayout />
    </Drawer>
  )
}

import { useFocusEffect } from 'one'

function Profile({ userId }) {
  const [user, setUser] = useState(null)

  useFocusEffect(
    () => {
      const unsubscribe = API.subscribe(userId, (user) => setUser(user))
      return () => unsubscribe()
    },
    [userId]
  )

  return <ProfileContent user={user} />
}

import { ScrollView } from 'react-native'
import { useHeaderHeight } from 'one'

export default function FeedScreen() {
  const headerHeight = useHeaderHeight()

  return <ScrollView contentContainerStyle={{ paddingTop: headerHeight }} />
}

import { useIsFocused } from 'one'

export default function ProfileScreen() {
  const isFocused = useIsFocused()

  return (
    <View>
      <Text>{isFocused ? 'Screen is focused' : 'Screen is not focused'}</Text>
    </View>
  )
}

import { useLinkTo } from 'one'
import { Pressable, Text } from 'react-native'

export default function CustomLinkButton() {
  const linkProps = useLinkTo({ href: '/profile' })

  return (
    <Pressable {...linkProps}>
      <Text>Go to Profile</Text>
    </Pressable>
  )
}

type LinkToProps = {
  href: Href
  replace?: boolean
}

type LinkToResult = {
  href: string
  role: 'link'
  onPress: (event?: React.MouseEvent<HTMLAnchorElement, MouseEvent> | GestureResponderEvent) => void
}