CORE CONCEPTS

Environment Variables

Rasengan.js reads .env* files automatically. There are two separate mechanisms, depending on where the variable needs to be visible:

Client-side: variables prefixed with RASENGAN_ are bundled into the browser JavaScript and exposed via import.meta.env.
Server-side: every variable (no prefix required) is loaded into process.env, available in SSR code, loaders, and _api/ route handlers.

Never prefix a secret with RASENGAN_

Anything matching the RASENGAN_ prefix ships to the browser as plain text in the client bundle. Database URLs, API secrets, and anything else server-only should be named without that prefix, so they only ever reach process.env on the server.

Client-Side: import.meta.env

Variables prefixed with RASENGAN_ are inlined into the client bundle at build time.

.env

RASENGAN_API_URL=https://api.example.com
RASENGAN_APP_NAME=My App

src/app/home.page.js

import.meta.env.RASENGAN_API_URL; // 'https://api.example.com'
import.meta.env.RASENGAN_APP_NAME; // 'My App'

This is a build-time replacement (Vite's own mechanism): only RASENGAN_-prefixed keys are ever considered, and only inside code that actually runs in the browser.

Server-Side: process.env

Every other variable, in any .env* file, is loaded into process.env automatically, with no prefix restriction and no manual dotenv setup needed. This covers SSR rendering, loader/generatePaths functions, and _api/ route handlers:

.env

DATABASE_URL=postgres://user:pass@localhost:5432/app
STRIPE_SECRET_KEY=sk_live_...

src/app/_api/orders.route.ts

import { json } from 'rasengan/server';
 
export async function GET() {
  const dbUrl = process.env.DATABASE_URL; // available, no import needed
  // ...
  return json({ ok: true });
}

File Precedence

Four filenames are checked, in this order, later files overriding earlier ones for the same key:

Order	File	Typical use
1	`.env`	Defaults shared across the team, usually committed
2	`.env.local`	Personal overrides, git-ignored
3	`.env.{mode}`	Mode-specific values (`.env.development`, `.env.production`)
4	`.env.{mode}.local`	Personal, mode-specific overrides, git-ignored

{mode} is development for rasengan dev and production for rasengan build.

A real environment variable always wins

If a variable is already set in the real process environment (your shell, CI, or a platform-injected secret on Vercel/Netlify), the value from a .env* file never overrides it. Files only fill in what isn't already set.

Where Loading Happens

Loading runs at the earliest possible point, before your own code (including rasengan.config.js) is ever imported:

rasengan dev: loaded before rasengan.config.js and before Vite's dev server starts, so _api/ routes, page loaders, and the config file itself all see it.
rasengan build: loaded before the build (and prerendering) starts, so generatePaths()/loader() functions called during static generation see it too.

The dev server's startup banner confirms which files were actually found, right below Runtime::

Rasengan v2.0.0-beta.4 running
 
→ Local:   http://localhost:5320
→ Network: http://192.168.4.144:5320
→ Runtime: Node.js
→ Env:     .env, .env.local

No line appears if no .env* file exists in the project.

TypeScript

Modules Aliases

Discover Plus Ultra ✨