DOCSEARCHbyAlgolia
Submit Docs

One React Framework

repository·main·Indexed 26 days ago

https://github.com/onejs/one

A React Framework that leverages Vite to serve both native mobile and web platforms from a single codebase. It features a Stack Header Composition API for declarative JSX configuration of native navigation headers, a set of headless UI components via `one/ui` for tab systems, and `@vxrn/mdx-rust`, a high-performance MDX pipeline using the satteri Rust-based parser and Expressive Code for syntax highlighting.

Tokens
129.1K
Snippets
357
Records
826
Agent score
88%

What's inside One

  1. Introduction to One

    main
    One is a React framework designed for full-stack development that enables targeting both React Native and web from a single codebase. It replaces both Metro and separate web frameworks with a unified framework using shared file-system routing. One runs on Vite and supports multiple render modes (SSG, SSR, SPA, and API) on a per-page basis. For native builds, it supports Metro (recommended for stability) and an experimental Vite-based bundler.

  2. Overview of @vxrn/mdx-rust

    main
    @vxrn/mdx-rust is a high-performance MDX pipeline for One. It uses the satteri Rust-based parser for fast Markdown/MDX compilation and Expressive Code (Shiki) for syntax highlighting. It includes built-in support for GFM, SmartyPants, frontmatter, and ::: directives. It is designed as a faster, lighter replacement for the mdx-bundler + remark/rehype stack used in @vxrn/mdx.

  3. Overview of One React Framework

    main
    One is a React Framework designed to allow Vite to serve both native (mobile) and web platforms from a single codebase. It leverages Vite to unify the development and serving experience across these environments.

  4. Compare One vs Next.js

    main

    One differs from Next.js in its approach to data and platform support:

    • Data Fetching: One uses loaders (similar to Remix) instead of React Server Components (RSC). It recommends pairing with a sync engine like Zero.
    • Cross-Platform: One targets React Native alongside web with a single codebase, whereas Next.js is web-focused.
    • Out-of-the-box features: One includes image optimization, dynamic OpenGraph images, automatic sitemaps, a Hono production server, and API routes.

  5. Understand One file-system routing

    main

    One uses file-system routing within the app directory. Every .tsx file in app becomes a route (a "page"), except for _layout.tsx, _middleware.tsx, or files matching your ignoredRouteFiles configuration.

    Pages must export a React component. You can use export default or a named export. Using a named export (the first capitalized one found) is recommended for better hot reloading support with React Refresh.

  6. Understand the Cloudflare Worker Build Pipeline

    main

    The Cloudflare build process consists of four sequential passes to generate the necessary assets and the worker entry point:

    1. Pass 1 (Client + Server): Runs viteBuild() for both client and ssr environments.
      • Outputs dist/client/* (static assets) and dist/server/* (server entry and shared chunks).
    2. Pass 2 (API Routes): Runs buildCustomRoutes('api', ...) to create fully-bundled ES modules for each API route.
      • Outputs dist/api/api/<route>.js.
    3. Pass 3 (Middlewares): Runs buildCustomRoutes('middlewares', ...) to bundle middleware files.
      • Outputs dist/middlewares/.
    4. Pass 4 (Cloudflare Worker): Generates a _worker-src.js file that creates a lazyRoutes map using dynamic imports pointing to the outputs of Passes 1, 2, and 3. This file is then bundled into the final dist/worker.js and dist/wrangler.jsonc using @cloudflare/vite-plugin to ensure proper polyfilling and CJS compatibility.

  8. Compare One vs Expo Router

    main

    While One started as a fork of Expo Router, it has diverged to provide several web-specific optimizations:

    • Rendering: One supports SSG, SSR, and SPA on a per-page basis via render modes. Expo Router is SPA-only on web.
    • Performance: One achieves higher Lighthouse scores through optimized loading and code splitting.
    • Server Features: One includes a Hono-based production server, middleware for request interception/auth, and typed loaders that tree-shake out of client bundles.
    • Dev Tools: One provides built-in dev tools (Alt+Space) with SEO preview, route debugging, and a source inspector.

    Note: Expo Router currently supports features One does not, such as use dom and RSC support.

  10. Compare One vs TanStack Start

    main

    Both are Vite-based, but they differ in configuration and execution:

    • Render Mode Configuration: One uses file suffixes (e.g., page+ssg.tsx, page+ssr.tsx) and supports a defaultRenderMode. TanStack uses route property configuration.
    • Static Generation: One's SSG runs loaders at build time to output static HTML. TanStack's static prerendering is a post-build crawl.
    • Loader Execution: One's loaders run on the server and tree-shake out of client bundles. TanStack's loaders are isomorphic (running on server and then again on client during navigation).
    • Platform Support: One targets web and native; TanStack Start is web-only.

  12. Configure devtools in vite.config.ts

    main

    One provides development tools to debug and understand your app. These are enabled by default in development mode. You can enable/disable them all at once or configure individual tools like inspector and seoPreview via the one plugin configuration in vite.config.ts.

    Available tools:

    • inspector: Hold Shift+Cmd (Mac) or Shift+Ctrl (Windows/Linux) and hover over an element to see its source file location and click to open it.
    • seoPreview: Press Alt+S to toggle a panel showing Google Search, Open Graph, and Twitter Card previews.
    • routeDebug: Press Alt+R to view current route state (Pathname, Segments, Params, etc.).
    • loaderTiming: Press Alt+L to view a performance waterfall for route loaders.
    • routePreload: Press Alt+P to view preloaded routes (Note: preloading only works in production builds).
    • errorPanel: Press Alt+E to view a history of errors caught by error boundaries and loaders.
    export default {
  plugins: [
    one({
      // Enable all devtools (default)
      devtools: true,

      // Disable all devtools
      devtools: false,

      // Configure individual tools
      devtools: {
        inspector: true, // enabled by default
        seoPreview: true, // enabled by default
      },
    }),
  ],
}