Environment

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.

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.

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.