Casting your Environment Variables to real javascript's type.
⚡️ 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.
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 */ }),
],
})
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,456]
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", 456]
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]
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"]
By default, this plugin only supports these 4 types: boolean
, string
, number
, (number | string)[]
.
If you need to cast others type, try to add your custom caster.
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", ...]
}
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]
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";
},
}
},
}),
],
})
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 |