onestack.dev/docs/

Public Link
Created by:
****ad@vlad.studio
Starting URLs:
https://onestack.dev/docs/installation
Crawl Prefixes:
https://onestack.dev/docs/
Exclude Patterns:
https://onestack.dev/docs/common-issues
https://onestack.dev/docs/guides
https://onestack.dev/docs/status
https://onestack.dev/docs/faq
https://onestack.dev/docs/features
## Page: https://onestack.dev/docs/installation

### A quick tutorial from start to finish

Getting started with One is as as easy as:

`npx one`

The CLI will guide you through the process of bootstrapping one of our starter templates.

If this is your first One app, we recommend taking this route, as you can choose between bare-bones example all the way up to a full stack with a user system and authentication. We will be launching more starters as the project matures.

### 5-minute tutorial

While we recommend using a preset to get started, it's helpful to walk through creating a new One app from scratch.

For those of you who prefer to learn by doing, we've put together a 5-minute tutorial that will have you building a basic app in no time.

Let's begin with our package.json:

package.json

`{` 

`"name": "one-app",` 

`"version": "0.0.0",` 

`"type": "module",` 

`"scripts": {` 

`"dev": "one dev",` 

`"build": "one build",` 

`"serve": "one serve"` 

`},` 

`"dependencies": {` 

`"one": "latest",` 

`"react": "~19.0.0",` 

`"react-native": "~0.79.2",` 

`"react-native-web": "~0.20.0"` 

`},` 

`"devDependencies": {` 

`"vite": "^6.1.0"` 

`}` 

`}` 

It is strongly recommended to pin the `one` version for production stability:

`npm install one@latest --save-exact`

This ensures consistent behavior across different environments and deployments.

If using pnpm or a package manager that symlinks dependencies, you'll want to disable that setting. One has (just a few) patches that fix dependencies. In part this is to enable switching between React 19 on web and React 18 on native, in part this is because the React Native ecosystem has many, many weirdly published packages - think JSX or Flowtype published in `.js` files, or non-standard legacy babel experimental transforms, etc. We are working with package authors to improve this, but we've found patches to be both simpler and require less mysterious behavior/slowdowns than the alternative of making Vite handle everything internally.

### Vite Config

Next, let's add our ultra-simple `vite.config.ts`:

vite.config.ts

`// Typed as UserConfig for handy autocomplete` 

`import type { UserConfig } from 'vite'` 

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

`export default {` 

 `plugins: [` 

`one(),` 

`],` 

`} satisfies UserConfig` 

### TSConfig

One will create a TSConfig for you when you first start the dev server, with some defaults that work well. Of course you can create your own if you'd prefer. The default looks like this:

`{` 

`"compilerOptions": {` 

`"baseUrl": ".",` 

`"paths": {` 

`"~/*": [` 

`"./*"` 

`]` 

`},` 

`"strict": true,` 

`"rootDir": ".",` 

`"module": "Preserve",` 

`"moduleResolution": "Bundler",` 

`"preserveSymlinks": true,` 

`"skipLibCheck": true,` 

`"jsx": "react-jsx",` 

`"noImplicitAny": false,` 

`"types": [` 

`"node",` 

`"react",` 

`"vite/client"` 

`],` 

`"lib": [` 

`"dom",` 

`"esnext"` 

`]` 

`},` 

`"exclude": [` 

`"node_modules",` 

`".expo",` 

`"**/test",` 

`"**/dist",` 

`"**/types",` 

`"**/tests"` 

`]` 

`}` 

### File System Routes

One expects your file system routes to be placed in an `app` directory.

`app/_layout.tsx` serves as the top-level wrapper for all routes, ideal for:

1.  Consistent page structure
2.  Global styles or themes
3.  Persistent navigation
4.  App-wide state management

One uses the `<Slot />` component to indicate where child components should render, allowing for nested layouts and fine-grained control over your UI structure.

Let's create a root layout `app/_layout.tsx`:

app/\_layout.tsx

`import { Slot } from 'one'` 

`export default function Layout() {` 

`return <Slot />` 

`}` 

And then create a simple index page `app/index.tsx`:

app/index.tsx

`import { View, Text } from "react-native";` 

`export default function MyApp() {` 

`return (` 

`<View style={{ flex: 1, justifyContent: "center", alignItems: "center", minHeight: "100%", }} >` 

 `<Text>Hello from One</Text>` 

 `</View>` 

`);` 

`}` 

You can now install your node modules and run your app. 🎉

`npm install && npm run dev`

### Running your app

If the port isn't taken, you should be able to load http://localhost:8081 and to see your website (use `--port` to change the port).

On native, you can use an Expo Go development app and load your app with exp://0.0.0.0:8081. Press the key combination q, r in your terminal which is running the dev server, and scan the QR code with your iPhone's camera if your computer and iPhone are connected to the same WiFi network.

Note that for web-only projects you don't need `react-native`, and further note that if you want something that has a much broader styling featureset and much lighter bundle-size on web, you can use Tamagui, which has no dependency on React Native.

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/introduction

### One is a React framework that aims to make full stack development as simple as possible - whether you're making a website, an app, or sharing code between the two.

One lets you target both React Native and web with a single codebase, replacing both Metro and a separate web framework with a single framework, with shared file-system routing. One runs on Vite, which brings many benefits.

## Highlights

*   Target native and web at once with typed file system routes.
*   Loaders ala Remix that tree-shake away on the client.
*   Routing modes on a per-page basis (SSG, SSR, SPA, and API).
*   Preloads all JS for initial load and when hovering links, without need for a route map.
*   Includes a production server out of the box.

## Use Cases

One works well as:

*   A uniquely good way to ship cross-platform apps with shared code.
*   A light, fast and opinionated framework for web-only or native-only.

Keep in mind, One is in early development and needs time to stabilize.

For a few more answers to common questions, see our FAQ.

## Our Full-Stack Philosophy

One lets you customize your stack as you please but recommends Zero as the first-class solution to data. We think the client-side "sync engine" model it uses is a clear win-win for simpler code and better UX.

Today, we have a starter with `npx one` that sets up an early alpha of Zero, while we work on a more official solution that neatly integrates One and Zero out of the box.

## Acknowledgements

One started as an experiment in porting Expo Router to our vxrn library. We since changed much of the internals and added render modes and a variety of features. We owe the Expo team a huge thanks for their pioneering efforts.

One was built thanks to some amazing open source technologies and contributors:

*   React Navigation provides the base routing library.
*   Expo Router for large parts of the initial One router.
*   Software Mansion for React Native Screens and React Native Gesture Handler.
*   Remix for inspiration for the `loader` APIs.
*   Vite, of course.

And a special thanks to the following individuals:

*   Matias Capeletto for inviting us to speak at ViteConf, giving the initial spark.
*   Fatih Aygün for freely helping at length, getting us past many hurdles.
*   Hiroshi Ogawa for his expert consulting for which One wouldn't exist without.
*   Dan Maier, for graciously gifting us the `one` npm package.

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/configuration

`import type { UserConfig } from 'vite'`

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

`export default {`

`plugins: [`

`one({`

`// all web-specific configuration nests in web:`

`web: {`

`// Choose the default strategy for routes without path-specifiers to render in`

`// can be one of "spa", "ssg" or "ssr"`

`defaultRenderMode: 'spa', // defaults to 'ssg'`

`// If using a server-rendered render mode, looseHydration will collapse large hydration`

`// error logs in development mode. React can gracefully recover from hydration issues,`

`// and they can often be ignored, but by default React produces large error logs.`

`// Turning this on will collapse those logs to one line.`

`looseHydration: false, // defaults to true`

`// Define server redirects for development and production`

`redirects: [`

`{`

`source: '/vite',`

`destination: 'https://vxrn.dev',`

`permanent: true,`

`},`

`{`

`source: '/docs/components/:slug/:version',`

`destination: '/ui/:slug/:version',`

`permanent: true,`

`},`

`],`

`},`

`/**`

`* Path to a js or ts file to import before the rest of your app runs`

`* One controls your root, but you may want to run some JS before anything else`

`* Use this to give One the entrypoint to run`

`*/`

`setupFile: './setup.ts',`

`optimization: {`

`/**`

`* Turn on [vite-plugin-barrel](https://github.com/JiangWeixian/vite-plugin-barrel/tree/master).`

`* Optimizes barrel export files to speed up your build, you must list the packages that have`

`* barrel exports. Especially useful for icon packs.`

`*`

`* @default ['@tamagui/lucide-icons']`

`* @type boolean | string[]`

`*/`

`barrel: ['my-icon-package']`

`},`

`// native-specific config:`

`native: {`

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

`// This setting determines app.key and must match the React Native app container you've built`

`key: 'AppName',`

`},`

`config: {`

`// Disable or configure the auto-added vite-tsconfig-paths`

`// https://www.npmjs.com/package/vite-tsconfig-paths`

`tsConfigPaths: false`

`// Disable auto-adding default tsconfig.json if not found`

`ensureTSConfig: false`

`},`

`server: {`

`// Configures production server to be compatible`

`// defaults to node`

`platform: 'node' | 'vercel'`

`},`

`react: {`

`// enable the new react compiler`

`compiler: true,`

`// react-scan support, must add the react-scan package to your package.json`

`// native is experimental, web is better supported`

`scan: true | 'web' | 'native',`

`},`

`// The deps configuration is a powerful way to apply patches to node_modules`

`// to configure patching and optimizeDeps for server-side.`

`// we found the React Native and general node module package ecosystem to not always`

`// play nice with universal apps, and this provides an easy way to configure them`

`deps: {`

`'moti/author': true,`

`'@sentry/react-native': {`

`version: '~15.2.0',`

`'**/*.js': ['jsx']`

`}`

`},`

`/**`

`* Per-file control over how code transforms.`

`* Defaults to SWC, runs babel before SWC if:`

`*`

``* - options.react.compiler is `true`, on tsx files in your app``

``* - `react-native-reanimated` is in your dependencies and a file contains a reanimated keyword``

`*`

``* Otherwise One defaults to using `@swc/core`.``

`*`

`* Accepts a function:`

`*`

`* (props: {`

`* id: string`

`* code: string`

`* development: boolean`

`* environment: Environment`

`* reactForRNVersion: '18' | '19'`

`* }) =>`

`* | true // default transforms`

`* | false // no transforms`

`* | 'babel' // force babel default transform`

`* | 'swc' // force swc default transform`

`*`

`* // force babel, custom transform`

`*`

`* | {`

`* transform: 'babel'`

`* excludeDefaultPlugins?: boolean`

`* } & babel.TransformOptions`

`*`

`* // force swc, custom transform`

`*`

`* | {`

`* transform: 'swc'`

`* } & SWCOptions`

`*`

``* Babel defaults to preset `@babel/preset-typescript` with plugins:``

`*`

`* - @babel/plugin-transform-destructuring`

`* - @babel/plugin-transform-runtime`

`* - @babel/plugin-transform-react-jsx`

`* - @babel/plugin-transform-async-generator-functions`

`* - @babel/plugin-transform-async-to-generator`

`*`

`*`

`* SWC default to target es5 for native, es2020 for web.`

`*`

`*/`

`transform: true`

`})`

`]`

`} satisfies UserConfig`

---

## Page: https://onestack.dev/docs/environment

### Variables

#### 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 either `VITE_` (to match Vite convention) or `ONE_PUBLIC_`.

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.

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

### Preset environment variables

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

*   `ONE_CACHE_KEY` is set to a random number for each production build, or once for each development server run. You can use this to have a stable cache key across releases.
*   `VITE_ENVIRONMENT` is set to `"client"` for client-side web, `"server"` for server-side web, and `"ios`" or `"android"` for native platforms, respectively.
*   `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_APP_NAME` is set to your app.key setting
*   `TAMAGUI_REACT_19` is set to `1`, which turns on Tamagui React 19 mode automatically for you, for performance if using Tamagui.

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/routing

The `app` directory is where One handles universal file system routing. Every file you create in it will be turned into a route, except for files named `_layout` or `_middleware`. One only supports file system routes at this time, but we have a discussion for those who want to help us figure out a configuration-based approach.

Here's an example:

\_layout.tsx

Wraps all files in this directory and below

index.tsx

Matches "/"

blog

index.tsx

Matches "/blog"

\[slug\].tsx

Matches a single sub-path of "/blog", like "/blog/hello"

\[...rest\].tsx

Matches all sub-paths, like "/blog/hello/world"

One routes support the popular feature of nested layouts, via `_layout.tsx` files, and parallel render-as-you-fetch data loading via `export loader`.

## Route Structure

All `.tsx` files in the `app` dir are used to match your routes, besides layouts. Each individual file is referred to as a "page" to disambiguate them from the term "route," which we use to refer to the actual URL state in a browser on web (or React Navigation state on native).

All pages must export a React component to be rendered. You can choose between two ways to export it: `export default` or plain `export`. If you don't `default` export, we look for the first `export` that is capitalized. The reason we support this is simple - the React Refresh library doesn't support hot reloading default exports. We're looking into modifying it to support them for route files, but until then you may want to simply use `export` to maintain a nice hot reloading experience.

### Simple Routes

A simple page that matches the `/` route and will render on native and web:

app/index.tsx

`import { Text } from 'react-native'` 

`export default function HomePage() {` 

`return (` 

`<Text>Hello world</Text>` 

`)` 

`}` 

If you are targeting web-only, you may use HTML elements:

app/index.tsx

`export default function HomePage() {` 

`return (` 

`<div>Hello world</div>` 

`)` 

`}` 

All `index` files match against `/`, so `app/index.tsx` matches to your root `/` route. You can give your page a name as well, for example `app/about.tsx` will the `/about` route.

### Dynamic Routes

The segments of a route, for example `/hello/world`, are referred to as "route parameters" or just "params", where "hello" and "word" are each a single parameter. Pages can match against parameters dynamically in two ways: matching a single parameter, or matching all parameters below them.

#### Single Parameter Routes

One uses brackets to match against a single dynamic parameter: `./blog/[slug].tsx` matches `/blog/post-one` and `/blog/post-two`:

blog.tsx

index.tsx

Matches "/blog"

\[slug\].tsx

Matches a single sub-path of "/blog", like "/blog/hello"

One will match `./blog/[slug].tsx` to any `/blog/*` route, and pass in the parameters to the route as follows:

`import { useParams } from 'one'` 

`export function loader({ params }) {` 

`// params.slug will be a string matching the URL parameter` 

`}` 

`export default function BlogPostPage() {` 

`const params = useParams()` 

`// params.slug will be a string matching the URL parameter` 

`}` 

#### Rest Parameter Routes

Much like JavaScript supports rest parameters, One supports rest parameter routes which are defined using the `[...rest].tsx` syntax.

catalog.tsx

index.tsx

Matches "/catalog"

\[...rest\].tsx

Matches all sub-paths of "/catalog", like "/catalog/a/b/c"

In the case where a user navigates to `/catalog/a/b/c`, the `[...rest].tsx` route would receive a params prop as follows:

`import { useParams } from 'one'` 

`export function loader({ params }) {` 

`// params.rest is an array ['a', 'b', 'c']` 

`}` 

`export default function BlogPostPage() {` 

`const params = useParams()` 

`// params.rest is an array ['a', 'b', 'c']` 

`}` 

### Not found routes

To have a custom 404 page, you can create a `+not-found.tsx` route in any folder. It will act as the same as a `[...rest].tsx` route in that it will catch all sub-routes for that folder.

Simply export a React component (default or named) from your not found page and it will render with a 404 status code.

catalog.tsx

index.tsx

Matches "/catalog"

+not-found.tsx

Matches all non-matching sub-paths of "/catalog" with a 404 status code

## Routing Modes

You can choose a rendering strategy on a per-page basis using a filename suffix. For more on these modes, see the next documentation page, Routing Modes.

*   `route+ssg.tsx` - Matches "/route", but will render the page as a SSG route.
*   `route+spa.tsx` - Matches "/route", but will render the page as a SPA route.
*   `route+ssr.tsx` - Matches "/route", but will render the page as a SSR route.
*   `route+api.tsx` - Matches "/route", but will render the page as an API route.

## Routing per-platform

You can target a specific platform using the same specific extension convention as React Native - ie, using `.web.tsx`, `.native.tsx`, `.ios.tsx`, or `.android.tsx` as the last part of the filename.

This lets you diverge the routing based on the platform. For example:

index.tsx

Matches "/" on native"

index.web.tsx

Matches "/" on web

blog.web.tsx

Matches "/blog" on web, on native there will be no route

## Groups

You can define a group by naming a folder with surrounding parenthesis:

\_layout.tsx

(blog)

\_layout.tsx

This layout will nest inside the above layout

blog.tsx

Matches "/blog"

\[slug\].tsx

Matches a single sub-path of "/blog", like "/blog/hello"

Groups are useful for a couple reasons:

*   They're useful to organize similar things without forcing you to nest URL segments.
*   They let you nest layouts, also without nesting segments.

## Types

One generates types for your routes, so that you get type checking on a variety of things like the Link component.

The types are generated into your root directory, in a `routes.d.ts` file. You must make sure your tsconfig.json picks up this file.

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/routing-modes

A unique feature of One is the ability to seamlessly route across a variety of route modes. What this means in plain english, is that you can choose whether each individual page within your routes uses one of a few strategies, such as rendering statically at build time, or rendering on-demand at request time.

One supports the following routing modes, which are explained in detail below: `api`, `spa`, `ssr`, and `ssg`.

You can set your global routing mode with the One vite plugin. The default is `ssg`.

vite.config.ts

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

`export default {` 

 `plugins: [` 

`one({` 

 `web: {` 

 `defaultRenderMode: 'spa'` 

`}` 

`})` 

`]` 

`}` 

To specify the routing mode on a per-page basis, you add a suffix to the filename, like so:

*   `route+ssg.tsx` - Matches "/route", but will render the page as a SSG route.
*   `route+spa.tsx` - Matches "/route", but will render the page as a SPA route.
*   `route+ssr.tsx` - Matches "/route", but will render the page as a SSR route.
*   `route+api.tsx` - Matches "/route", but will render the page as an API route.

## Modes

Note that render modes mostly only apply to the web. On native, everything is essentially a SPA, with all the JS for every route included in the app the user downloads from the app store. Because native apps don't have to deal with the network, this SPA mode is ideal and has very little downsides.

### SSG (the default)

When you don't add a `+` suffix to your route, it will default to an "SSG" route, unless you set the `web.defaultRenderMode` configuration otherwise. An example of a SSG route would be something like `app/blog.tsx` if you haven't changed the defaultRenderMode, or if you have `app/blog+ssg.tsx`.

SSG Stands for "Server Side Generated", it's a strategy for web where you pre-render the entire HTML and CSS of a page at build-time fully on the server (or in CI) so that you can serve the page quickly from something like a CDN, without running any JavaScript at the time of request.

We chose SSG as the default behavior as it serves as a good balance between simplicity and performance. What it is less good at is serving dynamic content to an individual user.

That said - you can still do dynamic content on top of an SSG page. It's just that you'll have to have the dynamic content load in after the browser finishes downloading and parsing the JS for that page, and it will need to gracefully replace the static content that the user sees.

This pattern is great for things like a SaaS homepage that shows mostly static content, but where you may want to load a logged-in menu for the current user. It's not good for something like a logged-in dashboard.

### SPA

If you name a route with the `+spa` suffix, like `app/dashboard+spa.tsx`, it will no longer render on the server - either at build-time or at request. Instead, at build time One will build just the client-side JavaScript necessary.

This render mode is great for highly dynamic use cases. Think a Linear, or a Figma, a metrics dashboard, or a user account panel. It is simpler to build, and doesn't require making sure every dependency works on both Node.js and in the browser.

It's downsides include a slower initial load time, and worse SEO. Though we are working on allowing `_layout.tsx` files to also leverage render modes, in which case you could have a really nice hybrid mode where you render layouts statically or on the server, but keep the "meat" of the page dynamic. This would retain some upsides of SSR/SSG, while simplifying things quite a bit.

### SSR

If you name a route with the `+ssr` suffix, like `app/issues+ssr.tsx`, you will get a server rendered page. This mode will generate the JS for both server and client at build-time, but instead of rendering out the HTML and CSS right then, it will instead wait for a request to the production server before it imports the server JS, renders the page, and then returns the HTML and CSS.

This mode is great for things that need to be dynamically rendered more often than whenever you deploy. One example is something more like GitHub Issues. By server rendering a page like this, you get faster initial loads, and better SEO than a SPA-type page. But it is the most expensive in terms of cost - each request will now run a full render of the route, and also slower than SSG in terms of initial response time, at least by default.

In the case of a GitHub Issues type page, what you'd do is cache the SSR response on a CDN, and then clear the CDN cache whenever data for that page updates. This is complex, and generally SSR is the most complex of the three render modes to support. Because it is more complex and more expensive, we generally recommend using SPA or SSG unless you are certain you can afford to pay for the extra render cost, and/or cache responses without too much trouble.

### API

Adding `+api.tsx` to the end of your filename turns a route into an API route. This is a special type of route that is different from the other types in that it expect to be used as an API endpoint that you call from other routes or services, and not as a place an end-user would navigate to directly via their browser.

API routes have a few standard exports. The default export acts as a catch-all:

`export default (request: Request): Response => {` 

`return Response.json({` 

 `hello: 'world'` 

`})` 

`}` 

We've aligned API routes with the Web standard Request and Response objects. This ensures they will be easy to use, well documented, and have broad compatibility with web servers. Note that TypeScript and Node >= 20 ships by default with global Request and Response objects, so you don't need to import them at all.

If you define a `./app/test+api.tsx` page with the above code, you can `curl https://localhost:3000/test` and you will receive a response with `Content-Type` set to `application/json`, and the contents of `{"hello":"world"}`.

You may also export a function for each of the supported HTTP types:

`export const GET = (request: Request): Response => {` 

`return Response.json({` 

 `hello: 'world'` 

`})` 

`}` 

One exports a type helper called `Endpoint` that you can use to make typing easier:

`import { Endpoint } from 'one'` 

`// this route will be typed as "(request: Request) => Response | Promise<Response>"` 

`export const GET: Endpoint = (request) => {` 

`return Response.json({` 

 `hello: 'world'` 

`})` 

`}` 

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/one-serve

Serve your web apps for production with `one serve`, after you've successfully run `one build`.

It takes the following arguments:

Terminal

`--host # string, set the hostname to bind to` 

`--port # string, set the port to bind to` 

`--platform # node | vercel, instructs Hono server to use adapter` 

`--compress # boolean, enable gzip compression, defaults to true` 

One comes with a serve command that is powered by Hono.

If you are only using SPA and SSG routes and aren't using loaders, you don't need to use `one serve` if you don't want to - you can statically serve the results of `dist/client` using any server you'd like.

You must run a `one build` before serve.

You can also run your production server programatically:

`import { serve } from 'one/serve'` 

`await serve()` 

Which takes options:

`type ServeOptions = {` 

`// you can pass in your own Hono server` 

 `app?: Hono` 

 `host?: string` 

 `port?: number` 

 `compress?: boolean` 

`/**` 

 `* Whether to run the Vite logic to load .env files before running the server` 

 `* @default false` 

 `*/` 

 `loadEnv?: boolean` 

`}` 

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/components-Link

`import { TextProps } from 'react-native'`

`export interface LinkProps extends TextProps {`

`children?: React.ReactNode`

`/** Path to navigate to. */`

`href: Href`

`/** Forward props to child component. Useful for custom buttons. */`

`asChild?: boolean`

`/** Replace the current route without adding to the history. */`

`replace?: boolean`

`/** Should push the current route */`

`push?: boolean`

``/** On web, this sets the HTML `class` directly. On native, no-op or can be used via a compile-time plugin. */``

`className?: string`

`onPress?: (e:`

`React.MouseEvent<HTMLAnchorElement, MouseEvent>`

`| GestureResponderEvent`

`) => void`

`/**`

``* **Web only:** Specifies where to open the `href`.``

`*`

`* - **_self**: the current tab.`

`* - **_blank**: opens in a new tab or window.`

`* - **_parent**: opens in the parent browsing context. If no parent, defaults to **_self**.`

`* - **_top**: opens in the highest browsing context ancestor. If no ancestors, defaults to **_self**.`

`*`

``* This property is passed to the underlying anchor (`<a>`) tag.``

`*`

`* @default '_self'`

`*`

`* @example`

`* <Link href="https://tamagui.dev" target="_blank">Open in new tab</Link>`

`*/`

`target?: '_self' | '_blank' | '_parent' | '_top' | string`

`/**`

``* **Web only:** Specifies the relationship between the `href` and the current route.``

`*`

`* Common values:`

``* - **nofollow**: Indicates to search engines that they should not follow the `href`. This is often used for user-generated content or links that should not influence search engine rankings.``

``* - **noopener**: Suggests that the `href` should not have access to the opening window's `window.opener` object, which is a security measure to prevent potentially harmful behavior in cases of links that open new tabs or windows.``

``* - **noreferrer**: Requests that the browser not send the `Referer` HTTP header when navigating to the `href`. This can enhance user privacy.``

`*`

``* The `rel` property is primarily used for informational and instructive purposes, helping browsers and web``

`* crawlers make better decisions about how to handle and interpret the links on a web page. It is important`

``* to use appropriate `rel` values to ensure that links behave as intended and adhere to best practices for web``

`* development and SEO (Search Engine Optimization).`

`*`

``* This property is passed to the underlying anchor (`<a>`) tag.``

`*`

`* @example`

`* <Link href="https://tamagui.dev" rel="nofollow">Open</Link>`

`*/`

`rel?: string`

`/**`

``* **Web only:** Specifies that the `href` should be downloaded when the user clicks on the link,``

`* instead of navigating to it. It is typically used for links that point to files that the user should download,`

`* such as PDFs, images, documents, etc.`

`*`

``* The value of the `download` property, which represents the filename for the downloaded file.``

``* This property is passed to the underlying anchor (`<a>`) tag.``

`*`

`* @example`

`* <Link href="/image.jpg" download="my-image.jpg">Download image</Link>`

`*/`

`download?: string`

`}`

---

## Page: https://onestack.dev/docs/routing-exports

This page catalogs all the special exports One supports from route files.

Note that `_layout` routes are special and do not support these exports unless specified.

### generateStaticParams

This export is needed for "ssg" type pages that use dynamic path segments (for example, `[id].tsx`). At build-time, One will expand the id segment into multiple pages, using the values you return from `generateStaticParams`.

The entire function and export `generateStaticParams` will be removed at build-time and everything it depends on will be tree-shaken out of your client-side bundle.

You'll need to return an array of objects, where the object keys match the name inside the brackets. As an example, we'll use nested dynamic segments:

app/blog/\[month\]/\[year\]/\[slug\]+ssg.tsx

`export async function generateStaticParams() {` 

`const blogPosts = await getAllBlogPosts()` 

`return blogPosts.map(post => {` 

`return {` 

 `month: post.month,` 

 `year: post.year,` 

 `slug: post.slug,` 

`}` 

`})` 

`}` 

If this function returned this:

`[` 

`{` 

 `month: 10,` 

 `year: 2025,` 

 `slug: 'some-slug'` 

`}` 

`]` 

Then you'd generate one page at `/blog/10/2025/some-slug`.

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/one-build

Building your app for production happens through `one build`.

It takes the first argument as the platform, which defaults to `web`.

`npx one build [web | ios | android]`

To build for iOS for example, you would run:

`npx one build ios`

## Building for web

When building One for web, the output will be a mostly static directory of HTML, CSS, and JavaScript. Internally, One runs a few different Vite production builds to output client, server, and API folders. This output is always in the `dist` directory.

Ensure your `.env` file has a `ONE_SERVER_URL` set to your production URL, like:

Terminal

`ONE_SERVER_URL=https://onestack.dev` 

We provide a production server based on Hono with `one serve` that handles loaders, SSR, and API routes for you. You can choose a deploy target for that server, for now we support `node` and `vercel` (in beta). This can be chosen via your Vite configuration:

vite.config.ts

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

`export default {` 

 `plugins: [` 

`one({` 

 `web: {` 

 `deploy: 'vercel' // defaults to node` 

`}` 

`})` 

`]` 

`}` 

The CLI will print instructions on how to deploy to the respective platform you choose after you run `npx one build`.

If you are only using SPA and SSG routes and aren't using loaders, you can statically serve the results of `dist/client` using any server you'd like.

## Building for native

We don't have an end-to-end build command yet, but One is designed to be easy to integrate into existing Expo or React Native build processes.

If you're familiar with EAS, see how to Build and Deliver Native Apps with EAS.

Or check out the iOS Native Guide for instructions on building your iOS app with Xcode.

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/exports-withLayoutContext

### Create your own layouts.

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

A good example of this is the new `react-native-bottom-tabs` library, that exports a React Navigation compatible navigator.

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

`import { createNativeBottomTabNavigator } from '@bottom-tabs/react-navigation'` 

`import { withLayoutContext } from 'one'` 

`const NativeTabsNavigator = createNativeBottomTabNavigator().Navigator` 

`export const NativeTabs = withLayoutContext(` 

 `NativeTabsNavigator` 

`)` 

Now you can use `NativeTabs` in any `_layout.tsx` file.

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/components-Redirect

Redirect to another page when this page is focused.

This component uses `useFocusEffect` to only run when the route it's rendered inside of is active. Once active, it will redirect immediately to a new route.

### Props

Terminal

`interface RedirectProps { href: string }` 

PreviousLink

Next

LoadProgressBar

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/routing-navigation

When you want to move between a page, you have a few options. Examples on this page will reference this routing structure:

\_layout.tsx

Wraps all files in this directory and below

index.tsx

Matches "/"

blog.tsx

index.tsx

Matches "/blog"

\[slug\].tsx

Matches a single sub-path of "/blog", like "/blog/hello"

## Link

You can use the Link component as follows:

app/index.tsx

`import { Link } from 'one'` 

`export default function HomePage() {` 

`return (` 

`<>` 

 `<Link href="/blog">` 

 `Go to the blog` 

 `</Link>` 

 `<Link href="/blog/introducing-one">` 

 `Go to the Introducing One article` 

 `</Link>` 

 `</>` 

`)` 

`}` 

Link accepts the following props, where `Href` is your typed file system routes (or a string if you turn off typed file system routing) and `TextProps` is the React Native Text element props:

`export interface LinkProps extends TextProps {` 

`/** Path to route to. */` 

 `href: Href` 

`/** Forward props to child component. Useful for custom buttons. */` 

 `asChild?: boolean` 

`/** Should replace the current route without adding to the history. */` 

 `replace?: boolean` 

`/** Should push the current route */` 

 `push?: boolean` 

``/** On web, this sets the HTML `class` directly. On native, can be used with CSS interop tools. */`` 

 `className?: string` 

 `onPress?: (e: React.MouseEvent<HTMLAnchorElement, MouseEvent> | GestureResponderEvent) => void` 

`/**` 

 ``* **Web only:** Specifies where to open the `href`, passed to the underlying anchor (`<a>`) tag.`` 

 `* See: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target` 

 `*/` 

 `target?: '_self' | '_blank' | '_parent' | '_top' | (string & object)` 

`/**` 

 ``* **Web only:** Specifies the relationship between the `href` and the current route.`` 

 `* See: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel` 

 `*/` 

 `rel?: string` 

`/**` 

 ``* **Web only:** Specifies that the `href` should be downloaded when the user clicks on the link.`` 

 `*/` 

 `download?: string` 

`}` 

## useLinkTo

This hook will generate both an `href` string and an `onPress` function, see the useLinkTo docs for how to use it.

## useRouter

This hook returns a static object used for routing. It will never update, and is only used for imperatively controlling the router. Useful for programmatically controlling the routing, and choosing between a `push` or `replace`.

See the useRouter documentation page for more.

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/one-dev

Developing an app with One is as simple as `one dev`.

It takes the following arguments:

Terminal

`--clean # boolean, will clear all caches before running` 

`--host # string, set the hostname to bind to` 

`--port # string, set the port to bind to` 

`-- debug # turns on vite debugging` 

The One development server serves both web and native apps on the same port at the same time, and should hot reload both at once. When you see the `Server running on` message with a host and port, that is the same for both native and web.

### Under the hood

The development command does a few things:

*   Runs an underlying Vite development server
*   Sets up a parent server using vxrn for native

The vxrn library is developed by the One team, and is what enables One to build and serve React Native apps with Vite. The way it works today is that it runs a server above Vite, which adds endpoints to support the various endpoints that React Native expects in development.

We think we can eventually migrate this to be a single Vite server, but it was simpler for us to implement it this way - React Native expects to communicate over multiple websockets, and getting that set up properly was simpler with the two-server approach.

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/components-Slot

This component should only be rendered inside a `_layout.tsx` file, where it will serve as the location that children will render for routes below the layout.

This is the simplest option for rendering children, it does not create a Stack, Drawer, or Tab view, instead it just renders the children directly.

`import { Slot } from 'one'` 

`export default function Layout() {` 

`return (` 

`<Slot />` 

`)` 

`}` 

PreviousMiddlewares

Next

Stack

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/components-Stack

This component should only be rendered inside a `_layout.tsx` file, where it will serve as the location that children will render for routes below the layout.

Stack is simply a React Navigation Native Stack view and accepts the same props as React Navigation.

`import { Stack } from 'one'` 

`import { Button } from 'react-native'` 

`export default function Layout() {` 

`return (` 

`<Stack screenOptions={{ headerRight() { return ( <Button label="Settings" /> ) }, }} />` 

`)` 

`}` 

### Stack.Screen

You can customize the children of the Stack in your layout by passing a children prop to Stack has Stack.Screen elements, like so:

`import { Stack } from 'one'` 

`export default function Layout() {` 

`return (` 

`<Stack>` 

 `<Stack.Screen name="index" options={{ title: 'Feed' }} />` 

 `<Stack.Screen name="[id]" options={{ title: 'Post' }} />` 

 `<Stack.Screen name="sheet" options={{ presentation: 'formSheet', gestureDirection: 'vertical', animation: 'slide_from_bottom', headerShown: false, }} />` 

 `</Stack>` 

`)` 

`}` 

The `name` must match the full name of the file inside `app`, without the extension but including groups.

In this example we are setting `index`, `[id]`, and `sheet` screens, which would correspond to `index.tsx` and `[id].tsx` and `sheet.tsx` pages in the same directory.

This is a convenient way to configure settings for each page up front, but you could also render `Stack.Screen` inside each individual page so you can access data loaded inside that page. The upside of doing it in the layout is that it will configure things before any stack animation runs on enter, with the downside being that you can't access page-level data.

The `options` property passes to the React Navigation NativeStack, and so takes the same options.

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/components-Drawer

Notice - Drawer is current disabled as we work through a final issue with react-native-gesture-handler. It should be landing very shortly.

This component should only be rendered inside a `_layout.tsx` file, where it will serve as the location that children will render for routes below the layout.

Drawer is simply a React Navigation Drawer view and accepts the same props as React Navigation.

`import { Drawer } from 'one'` 

`export default function Layout() {` 

`return (` 

`<Drawer />` 

`)` 

`}` 

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/components-LoadProgressBar

`export type LoadProgressBarProps = {`

`/** How long after a navigation to wait before showing the progress bar (in ms) */`

`startDelay?: number`

`/** How long after a navigation completes to wait before hiding the progress bar (in ms) */`

`finishDelay?: number`

`/** The starting percent it should show the loading state at */`

`initialPercent?: number`

`/** How often the progress bar should update (in ms) */`

`updateInterval?: number`

`/** How often to skip an update (checked each during the loop) */`

`sporadicness?: number`

`/** Pass style to the inner View */`

`style?: ViewProps['style']`

`/** Pass onLayout to the inner View */`

`onLayout?: ViewProps['onLayout']`

`/** Pass children to the inner View */`

`children?: ViewProps['children']`

`}`

---

## Page: https://onestack.dev/docs/hooks-useLinkTo

Used to create props that can be passed to a React Native or web component for creating a custom link.

Accepts a single argument of type:

`type LinkToProps = {` 

 `href: Href;` 

 `replace?: boolean` 

`}` 

Note that `Href` is a string that is typed based on your file system routes.

Returns an object of type:

`type LinkToResult = {` 

 `href: string` 

 `role: 'link'` 

`onPress: (event: e?: React.MouseEvent<HTMLAnchorElement, MouseEvent> | GestureResponderEvent) => void` 

`}` 

PrevioususeIsFocused

Next

useLoader

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/hooks-useRouter

`type Router = {`

`/** Go back in the history. */`

`back: () => void`

``/** If there's history that supports invoking the `back` function. */``

`canGoBack: () => boolean`

`/** Navigate to the provided href using a push operation if possible. */`

`push: (href: Href, options?: LinkToOptions) => void`

`/** Navigate to the provided href. */`

`navigate: (href: Href, options?: LinkToOptions) => void`

`/** Navigate to route without appending to the history. */`

`replace: (href: Href, options?: LinkToOptions) => void`

`/** Navigate to the provided href using a push operation if possible. */`

`dismiss: (count?: number) => void`

`/** Navigate to first screen within the lowest stack. */`

`dismissAll: () => void`

``/** If there's history that supports invoking the `dismiss` and `dismissAll` function. */``

`canDismiss: () => boolean`

`/** Update the current route query params. */`

`setParams: <T = ''>(`

`params?: T extends '' ? Record<string, string | undefined | null> : InputRouteParams<T>`

`) => void`

`/** Subscribe to state updates from the router */`

`subscribe: (listener: RootStateListener) => () => void`

`/** Subscribe to loading state updates */`

`onLoadState: (listener: LoadingStateListener) => () => void`

`}`

---

## Page: https://onestack.dev/docs/routing-layouts

Layout files can be placed in any folder inside the `./app` directory. They serve as the frame for the routes contained within that folder, and they can nest inside of each other if you place them in sub-directories.

\_layout.tsx

Wraps all files in this directory and below

index.tsx

Matches "/"

blog

\_layout.tsx

A custom sub-layout for all /blog pages

index.tsx

Matches "/blog"

\[slug\].tsx

Matches a single sub-path of "/blog", like "/blog/hello"

Layouts must render one of the following to show the matched pages that exist in their directory:

*   Slot: Directly show sub-route with no frame.
*   Stack: Creates a React Navigation Stack of sub-routes.
*   Tabs: Creates a React Navigation BottomTabs with sub-routes.
*   Drawer: Creates a React Navigation Drawer with sub-routes.

This looks something like this at the simplest:

app/\_layout.tsx

`import { Slot } from 'one'` 

`export default function Layout() {` 

`return (` 

`<Slot />` 

`)` 

`}` 

As of now, layouts don't support loaders. If you need to access the current route params, you can use the useParams hook.

## Root Layout

The root layout on web controls the entire page, from `<html>` on down. You can optionally return `html`, `body`, and `head` elements in your `app/_layout.tsx` and they will "just work" - on web, it will be output, and on native it won't so as to avoid rendering errors:

app/\_layout.tsx

`import { Slot } from 'one'` 

`export default function Layout() {` 

`return (` 

`<html lang="en-US">` 

 `<head>` 

 `<meta charSet="utf-8" />` 

 `</head>` 

 `<body>` 

 `<Slot />` 

 `</body>` 

 `</html>` 

`)` 

`}` 

### useServerHeadInsertion

The root `_layout.tsx` can use a special hook that allows it to insert tags into your `<head />` tag after server rendering finishes. This is an edge-case that is mostly only useful for CSS-in-JS libraries. You can use it like so:

`import { Slot, useServerHeadInsertion } from 'one'` 

`export default function Layout() {` 

`useServerHeadInsertion(() => {` 

`// this will run after the entire page renders` 

`// return a single React.ReactElement that will be spliced into your <head />` 

`return <style>{renderCSS()}</style>` 

`})` 

`return (` 

`<html>` 

 `<Slot />` 

 `</html>` 

`)` 

`}` 

## Groups and layouts

If you'd like to logically group together some pages without creating a sub-route, you can use a group folder by naming it like so:

\_layout.tsx

Wraps all files in this directory and below

index.tsx

Matches "/"

(blog)

\_layout.tsx

A custom sub-layout for all /blog pages

blog.tsx

Matches "/blog"

\[slug\].tsx

Matches a single sub-path of "/blog", like "/blog/hello"

Groups let you add extra layouts. If done right, this gives you a lot of control over how your app feels.

## Nested layouts example

A common pattern that apps have is something like Twitter/X, where you have bottom tabs for your "top level" views, but then on some of the bottom tab sections, you want to have a Stack that remembers its state inside just that tab.

This pattern can be incredibly verbose to link together with React Navigation, and takes a bit of tinkering to figure out with One. Since it is common and a useful example, lets walk through how you'd build on using One's file system routing.

Here's our file structure:

\_layout.tsx

Where our Tabs layout is defined

notifications.tsx

Matches "/notifications"

profile.tsx

Matches "/profile"

(feed)

\_layout.tsx

Where our Stack layout is defined

index.tsx

Matches "/"

post-\[id\].tsx

Matches routes like "/post-123"

The top level Layout will define our tabs:

app/\_layout.tsx

`import { Bell, Home, User } from '@tamagui/lucide-icons'` 

`import { Home } from '~/features/icons'` 

`export function RootLayout() {` 

`return (` 

`<Tabs screenOptions={{ headerShown: false, }} >` 

 `<Tabs.Screen name="(feed)" options={{ title: 'Feed', tabBarIcon: ({ color }) => <Home size={20} color={color} />, }} />` 

 `<Tabs.Screen name="notifications" options={{ title: 'Notifications', tabBarIcon: ({ color }) => <Bell size={20} color={color} />, }} />` 

 `<Tabs.Screen name="profile" options={{ title: 'Profile', tabBarIcon: ({ color }) => <User size={20} color={color} />, }} />` 

 `</Tabs>` 

`)` 

`}` 

This will set us up with three bottom tabs: Feed, Notifications, and Profile. The Notifications and Profile tabs for now will just show their content directly, but inside of the Feed tab, we want to show a stack.

We set up the stack in `(feed)/_layout.tsx`:

(feed)/\_layout.tsx

`import { Slot, Stack } from 'one'` 

`export default function FeedLayout() {` 

`return (` 

`<>` 

 `{typeof window !== 'undefined' ? (` 

`<Slot />` 

`) : (` 

`<Stack>` 

 `<Stack.Screen name="index" options={{ title: 'Feed' }} />` 

 `<Stack.Screen name="[id]" options={{ title: 'Post' }} />` 

 `</Stack>` 

`)}` 

 `</>` 

`)` 

`}` 

One thing we're showing here is that the layout is diverging between web and native. On web, we are showing a Slot, while on Native we show a Stack. This is because browsers feel better without stacks - the native back/forward button serves as our stack controller.

On Native we are defining the configuration for each sub-screen with the `Stack.Screen` component. The Stack component is a React Navigation native stack navigator and nothing more, it accepts all the props you'd expect.

You'll notice we are matching the `name` to the file names names of the sub-routes, without the `.tsx` extension.

This will get you a nice Stack-inside-Tabs pattern that is common on native apps, all with just two layouts and a few routes.

## Limitations

As of today layouts don't support loaders. This is on our radar, please chime in if this is helpful for you.

Also note that `useParams` won't work in layouts, as they are never nested inside a route. Instead, you can use `useActiveParams`.

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/routing-middlewares

Developing

Place a `_middleware.ts` file anywhere inside your `app` directory to create a middleware.

Here's an example:

\_layout.tsx

Wraps all files in this directory and below

\_middleware.ts

Middleware for all "/" routes

index.tsx

Matches "/"

blog

\_middleware.ts

Middleware for all "/blog" routes

index.tsx

Matches "/blog"

Middlewares can be nested and will run from top to bottom on matching routes.

app/\_middleware.ts

`import { createMiddleware } from 'one'` 

`export default createMiddleware(async ({ request, next }) => {` 

``if (request.url.includes(`test-middleware`)) {`` 

`return Response.json({ middleware: 'works' })` 

`}` 

`const response = await next()` 

`if (!response && request.url.endsWith('/missing')) {` 

`return Response.json({ notFound: true })` 

`}` 

`return response` 

`})` 

The `createMiddleware` function is a simple helper for types. Middlewares receive one argument, an object with three properties:

*   `request` is a Request for the current request.
*   `next` is a function that returns a promise.
*   `context` is an Object which you can mutate to pass data between middlewares.

The `next` function will run the rest of the middlewares and then the current route, and will return the final Response. This lets you run some logic after the full route has been processed, and before it returns the final response.

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/components-Tabs

This component should only be rendered inside a `_layout.tsx` file, where it will serve as the location that children will render for routes below the layout.

Tabs is simply a React Navigation Bottom Tabs view and accepts the same props as React Navigation.

For now, you do need to set the `href` option on each Tabs.Screen to match the route file name. The plan is to automate this in the future.

`import { Tabs } from 'one'` 

`export default function Layout() {` 

`return (` 

`<Tabs>` 

 `<Tabs.Screen name="explore" options={{ title: 'Explore', href: '/explore', }} />` 

 `</Tabs>` 

`)` 

`}` 

Adding a new tab route has a bug currently that can cause it to not show up until you re-run your app with `--clean`.

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/components-ScrollBehavior

One automatically handles resetting scrolling to window.location.hash and changing scroll position to the top when you navigate to a new page.

It also remembers your scroll position on each page you've visited and restores that position when you navigate back or forward to it. This mimics the default behavior that browsers do with multi-page apps.

You can control this behavior by importing the `ScrollBehavior` component once in your app (we'd recommend doing so in your root `_layout.tsx`) and returning it in your component's virtual DOM.

ScrollBehavior accepts a `disabled` prop which takes values of type `boolean` or string `"restore"`. If set to "restore," the scroll position will only reset to the top on new page navigation, but won't be restored to the previous scroll position when navigating back/forward.

In general, you shouldn't need to use this component, but it may be helpful in specialized use cases where you need more control over the scroll restoration logic.

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/hooks-useIsFocused

Beta

Beta

X

Github

Discord

System

wwwwwwwwwwwwwwwwwww

Beta

Introduction

Installation

Configuration

Environment

Features

Status

FAQ

Re-export of useIsFocused from React Navigation.

Returns a boolean, `true` if the current screen is active.

PrevioususeFocusEffect

Next

useLinkTo

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/hooks-useLoader

`import { useLoader } from 'one'`

`export function loader() {`

`return { hello: 'world' }`

`}`

`export default function Page() {`

`const data = useLoader(loader)`

`return (`

`<>{data.hello}</>`

`)`

`}`

---

## Page: https://onestack.dev/docs/hooks-usePathname

Returns a string that represents the current pathname.

It takes no arguments and will update every time the route changes.

PrevioususeParams

Next

useRouter

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/helpers-utility-functions

All functions listed below are exported directly by `one`.

### redirect

A function that takes two arguments: a string `path`, and a 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.

### getURL

A function that takes no arguments and returns a string of the current URL of the running application on client or server.

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 `/`.

### isResponse

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.

### href

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`` 

### setServerData, getServerData

Developing

For improving performance of client hydration on the web, you can pass data from the server to the client. Data must be serializable to JSON.

Here's an example of a simple `useFetch`:

app/index.tsx

`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 server data must be set during render` 

`setServerData(url, await fetch(url).then(res => res.json()))` 

`}` 

`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.idl, 'data')` 

`return {}` 

`}` 

Developing

A convenience function for setting headers of the current response from anywhere on the server.

app/\_middleware.ts

`import { createMiddleware, setResponseHeaders } from 'one'` 

`export default createMiddleware(({ request }) => {` 

`ØsetResponseHeaders((headers) => {` 

 `headers.append('test-header', 'test-value')` 

`})` 

`})` 

Where `headers` is of type Headers.

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/routing-loader

## Loaders

Loaders are useful for one-time loading of data from the server to the client and can only be used in routes in your `app` directory.

Loaders run on the server, for now they run based on their render mode - during build-time for SSG routes, or on each request for SPA or SSR routes.

Loaders and their imports are removed from client bundles, so you can access private information from within the loader. The data returned from the loader will be passed to the client, and so should be clear of private information. To access the loader data on the client, you must use the `useLoader` hook:

`import { useLoader } from 'one'` 

`export async function loader() {` 

`return {` 

 `user: 'tamagui'` 

`}` 

`}` 

`export default function HomePage() {` 

`const data = useLoader(loader)` 

`return (` 

`<p>` 

 `{data.user}` 

 `</p>` 

`)` 

`}` 

The useLoader hook is automatically type safe.

## Loader arguments

Loaders receive a single argument object:

### params

The `params` key will provide values from any dynamic route segments:

app/user/\[id\].tsx

`export async function loader({ params }) {` 

`// for route /user/jamon params.id is a string "jamon"` 

`const user = await getUser(params.id)` 

`return {` 

 `` greet: `Hello ${user.name}` `` 

`}` 

`}` 

### path

The `path` key is the fully resolved pathname:

app/user/\[id\].tsx

`export async function loader({ path }) {` 

`// if the route is /user/123 then path is "/user/123"` 

`}` 

### request

Only for `ssr` type routes. This will pass the same Web standard Request object as API routes.

## Accepted Return Types

Most JavaScript values, including primitives and objects, will be converted to JSON.

You may also return a `Response`:

`export async function loader({ params: { id } }) {` 

`const user = await db.users.findOne({ id })` 

`const body = JSON.stringify(user)` 

`return new Response(body, {` 

 `headers: {` 

`'Content-Type': 'application/json',` 

`},` 

`})` 

`}` 

## Throwing a Response

A final handy pattern for loaders is throwing a response to end it early:

`export async function loader({ params: { id } }) {` 

`const user = await db.users.findOne({ id })` 

`if (!user) {` 

`throw Response.error()` 

`}` 

`// ... rest of function` 

`}` 

You can combine this with the redirect utility function:

`import { redirect } from 'one'` 

`export async function loader({ params: { id } }) {` 

`const user = await db.users.findOne({ id })` 

`if (!user) {` 

`throw redirect('/login')` 

`}` 

`// ... rest of function` 

`}` 

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/components-SafeAreaView

Exports SafeAreaView from react-native-safe-area-context. This enables easy "safe area" targeting for both web and native.

One uses the SafeAreaProvider from React Navigation to set this up.

We're working on improving this so you can control whether it is included and the initial window metrics on server.

PreviousScrollBehavior

Next

useActiveParams

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/hooks-useFocusEffect

System

wwwwwwwwwwwwwwwwwww

Similar to React `useEffect`, but only runs when the current route is focused. This is directly based off React Navigation's useFocusEffect.

You must pass it an array as the second argument to determine memoization, otherwise the effect will not change.

Example:

`import { useFocusEffect } from '@react-navigation/native'` 

`import { useCallback } from 'react'` 

`function Profile({ userId }) {` 

`const [user, setUser] = React.useState(null)` 

`useFocusEffect(` 

`() => {` 

`const unsubscribe = API.subscribe(userId, (user) => setUser(user))` 

`return () => unsubscribe()` 

`},` 

`[userId]` 

`)` 

`return <ProfileContent user={user} />` 

`}` 

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/hooks-useNavigation

Return the navigation object for the current route.

It takes an optional argument named `parent` of type `string`:

*   `parent` - Provide an absolute path like `/(root)` to the parent route or a relative path like `../../` to the parent route.

It returns the result of `useNavigation` from React Navigation, you can see the methods available on this object on the React Navigation navigation prop reference page.

You should prefer to use `useRouter` as it is strongly typed and only exposes functions that are guaranteed to work within One, but useNavigation gives you lower level access to the underling React Navigation instance.

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/hooks-useParams

Returns an object that describes the route segments. This will only update for the route it's used inside of, and avoids re-renders when, for example, a user navigates to another stack view that isn't matched.

This is the recommended way to access the URL parameters. If you need to access parameters across all routes, see useActiveParams.

PrevioususeNavigation

Next

usePathname

Edit this page on GitHub.

---

## Page: https://onestack.dev/docs/hooks-useActiveParams

This will return the segments of the current URL paths, including dynamic path segments.

Note that this function, as opposed to useParams, will update even when the path is not relevant to the route it is used inside. In general when you need to access params , use `useParams`, as these will only update when the route is focused.

This hook is useful for things like analytics where you need to access every change globally.

PreviousSafeAreaView

Next

useFocusEffect

Edit this page on GitHub.