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 VITE_ (Vite convention), EXPO_PUBLIC_ (Expo 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.

ONE_PUBLIC_ is One’s default naming convention, while EXPO_PUBLIC_ remains fully supported. A ONE_PUBLIC_ variable is also exposed under the matching EXPO_PUBLIC_ name when that Expo variable is absent. One does not create ONE_PUBLIC_ variables from Expo variables, and an explicitly defined Expo variable keeps its own value.

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.

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". Expo packages also receive EXPO_OS as "ios" or "android" in native builds; One does not define it on web.

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.

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.