Vite Env Caster

Casting your Environment Variables to real javascript's type.

✨ Features

⚡️ Fast: Everything is processed at build-time, zero run-time's code, your application has been no impacted.

🛠️ Simple: Starting use your environment variables with no configuration.

🔌 Customizable: Adding your custom caster or replacing default's caster.

Ts Typescript: Typescript supported.

Getting started

Installation

With yarn

yarn add @niku/vite-env-caster

With npm

npm i --save @niku/vite-env-caster

Then add EnvCaster to you Vite's plugins.

// vite.config.ts
import EnvCaster from '@niku/vite-env-caster';

export default defineConfig({
  plugins: [
    EnvCaster({ /* options */ }),
  ],
})

Usage

It's very simple.

Example:

You have file .env like this:

// .env.development
VITE_API_URL=http://example.com
VITE_DEFAULT_PAGE_SIZE=10
VITE_AUTH_ENABLED=false
VITE_ARRAY_EXAMPLE=[123,abc,def,false,456,true]

Then, you can import and use it's variables by import as a module.

// src/main.ts
import appEnv from "app-env";

console.log(appEnv.VITE_API_URL) // "http://example.com"
console.log(appEnv.VITE_DEFAULT_PAGE_SIZE) // 10
console.log(appEnv.VITE_AUTH_ENABLED) // false
console.log(appEnv.VITE_ARRAY_EXAMPLE) // [123, "abc", "def", false,456, true]

Force cast to type

If you need to cast environment variable to a static type, you can define that type in variable.

Example:

// .env.development
VITE_IS_A_NUMBER_IN_STRING=10|string
VITE_IS_A_BOOLEAN_IN_STRING=false|string
VITE_IS_ARRAY_OF_NUMBER=[123,abc,def,456]|array[number]
VITE_IS_ARRAY_OF_STRING=[123,abc,def,456]|array[string]
VITE_IS_ARRAY_OF_BOOLEAN=[true, false, abc, 0]|array[boolean]

Then.

// src/main.ts
import appEnv from "app-env";

console.log(appEnv.VITE_IS_A_NUMBER_IN_STRING) // "10"
console.log(appEnv.VITE_IS_A_BOOLEAN_IN_STRING) // "false"
console.log(appEnv.VITE_IS_ARRAY_OF_NUMBER) // [123, NaN, NaN, 456]
console.log(appEnv.VITE_IS_ARRAY_OF_STRING) // ["123", "abc", "def", "456"]
console.log(appEnv.VITE_IS_ARRAY_OF_BOOLEAN) // [true, false, true, false]

Limitation

By default, this plugin only supports these 4 types: boolean, string, number, (number | string | boolean)[].

If you need to cast others type, try to add your custom caster.

Typescript support

By default, file env.d.ts will be generated at root of project. You can include it in your tsconfig.json.

// tsconfig.json
{
  "include": ["env.d.ts", ...]
}

Configuration

Transform key

In some case, you may want to use environment variable with other convention. Like use with camel case and remove prefix VITE_. You can customize it very easy.

// vite.config.ts
import EnvCaster from '@niku/vite-env-caster';
import {camelCase} from "lodash";

export default defineConfig({
  plugins: [
    EnvCaster({
      transformKey: (plainKey) => camelCase(plainKey.replace("VITE_", ""))
    }),
  ],
})

Then, you can use environment variable in camel case.

// src/main.ts
import appEnv from "app-env";

console.log(appEnv.apiUrl) // "http://example.com"
console.log(appEnv.defaultPageSize) // 10
console.log(appEnv.authEnabled) // false
console.log(appEnv.arrayExample) // [123, "abc", "def", 456]

Custom Type Caster

This is an example for number caster.

// vite.config.ts
import EnvCaster from '@niku/vite-env-caster';
import {camelCase} from "lodash";

export default defineConfig({
  plugins: [
    EnvCaster({
      typeCasters: {
        number: {
          // Check if variable is number
          isType(plainValue, type) {
            if (type) { // Forced type
              return type.toLowerCase() === "number";
            }

            // Auto detect
            return !Number.isNaN(Number(plainValue));
          },
          // Cast variable to number
          castValue(plainValue) {
            return Number(plainValue);
          },
          // Type in declaration file
          typescriptType() {
            return "number";
          },
        }
      },
    }),
  ],
})

All options

| Option | Description | Default | | ------------ | ------------------------------------------------------------------------ | ---------- | | moduleName | Virtual module name you will import env from. | "app-env" | | exportName | Export module name will be generated in declaration file. | "appEnv" | | declaration | Should plugin generate declaration file. Can be passed a string as path. | "env.d.ts" | | typeCasters | List custom type casters. | No | | transformKey | A function to transform environment variable's key. | No |