Skip to main content

Quick Start

Get up and running with Meta Env Typed in just a few minutes.

Step 1: Install​

First, install Meta Env Typed as a development dependency:

npm install meta-env-typed -D

Step 2: Configure Your Build Tool​

For Vite Projects​

Add the plugin to your vite.config.ts:

vite.config.ts
import envTyped from 'meta-env-typed/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    envTyped()
  ]
});

For Rsbuild Projects​

Add the plugin to your rsbuild.config.ts:

rsbuild.config.ts
import { defineConfig } from '@rsbuild/core';
import envTyped from 'meta-env-typed/rsbuild';

export default defineConfig({
  plugins: [
    envTyped()
  ]
});

Step 3: Create Environment Variables​

Create a .env file in your project root:

.env
# For Vite (requires VITE_ prefix)
VITE_API_URL=https://api.example.com
VITE_APP_TITLE=My Awesome App
VITE_PORT=3000

# For Rsbuild (no prefix required by default)
API_URL=https://api.example.com
APP_TITLE=My Awesome App
PORT=3000

Step 4: Start Your Development Server​

Start your development server to trigger the type generation:

# For Vite
npm run dev

# For Rsbuild
npm run dev

Step 5: Use Your Typed Environment Variables​

The plugin automatically generates src/import_meta.d.ts with your environment variable types:

src/import_meta.d.ts
// This file is auto-generated by meta-env-typed
interface ImportMetaEnv {
  readonly VITE_API_URL: string;
  readonly VITE_APP_TITLE: string;
  readonly VITE_PORT: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

Now you can use your environment variables with full TypeScript support:

src/main.ts
// ✅ Full IntelliSense and type checking
console.log(import.meta.env.VITE_API_URL); // Type: string
console.log(import.meta.env.VITE_APP_TITLE); // Type: string
console.log(import.meta.env.VITE_PORT); // Type: string

// ✅ TypeScript will catch typos
console.log(import.meta.env.VITE_API_URl); // ❌ Error!

Step 6: Enable Value Types (Optional)​

For even better type safety, you can enable valueInType to get literal types:

vite.config.ts
import envTyped from 'meta-env-typed/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    envTyped({
      valueInType: true // Enable literal types
    })
  ]
});

This generates more specific types:

src/import_meta.d.ts
interface ImportMetaEnv {
  readonly VITE_API_URL: 'https://api.example.com'; // Literal type!
  readonly VITE_APP_TITLE: 'My Awesome App'; // Literal type!
  readonly VITE_PORT: '3000'; // Literal type!
}

That's It! 🎉​

You now have fully typed environment variables in your project. The types will automatically update whenever you modify your environment files.

Next Steps​

Common Issues​

Types Not Updating?​

If your types aren't updating after changing environment variables:

  1. Restart your development server
  2. Check that your environment file is in the project root
  3. Verify your environment variables have the correct prefix (for Vite: VITE_)

TypeScript Errors?​

Make sure your tsconfig.json includes the generated types file:

tsconfig.json
{
  "compilerOptions": {
    "types": ["vite/client"]
  },
  "include": [
    "src/**/*",
    "src/import_meta.d.ts" // Make sure this is included
  ]
}