Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mrspartak/config
Typescript runtime configuration resolver
https://github.com/mrspartak/config
configuration javascript superstruct typescript valibot validation yup zod
Last synced: 15 days ago
JSON representation
Typescript runtime configuration resolver
- Host: GitHub
- URL: https://github.com/mrspartak/config
- Owner: mrspartak
- License: mit
- Created: 2024-06-07T21:25:12.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2024-06-22T21:31:45.000Z (5 months ago)
- Last Synced: 2024-10-01T22:38:28.241Z (about 1 month ago)
- Topics: configuration, javascript, superstruct, typescript, valibot, validation, yup, zod
- Language: TypeScript
- Homepage: https://mrspartak.github.io/config/
- Size: 464 KB
- Stars: 21
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🔧 Typescript runtime configuration resolver
@mrspartak/config is a robust TypeScript runtime configuration resolver designed to ensure that your application runs with the correct settings every time. It supports dynamic runtime validation, deep merging of configurations, and integrates seamlessly with your choice of data validation libraries.
- ⚡️ **Runtime Validation**: Ensure your application never runs with the wrong configuration.
- 🧙♂️ **TypeScript IntelliSense**: Leverage auto-completion and type-checking at development time.
- 🍃 **Zero Dependencies**: Lightweight with no external dependencies
- 🤲 **Flexible Configuration Merging**: Supports merging multiple configurations with a default overwrite strategy.
- 👓 **Versatile Configuration Sources**: Load from JSON files, URLs, or direct objects. Inderect .env support
- 🐻 **Extensible Validation Support**: Compatible with **Zod**, **Valibot**, **Yup**, **Superstruct**, and more.
- ✅ **Production Ready**: Thoroughly tested and stable for use.
- 📦 **Front-end friendly**: Can be used on a front-end with bundlers.
## Installation
```sh
# yarn
yarn add @mrspartak/config
# npm
npm i @mrspartak/config
# pnpm
pnpm add @mrspartak/config
# bun
bun add @mrspartak/config
```
## Mentions
- [My article on how to do configurations](https://medium.com/@assorium/mastering-typescript-runtime-configurations-5dbfec90be87)
## Using with JSON config on a back-end
> This is a recomended way of doing back-end run-time configuration. It allows to have readable structures and can be used with configmaps and secrets on deploy.
```ts
// file: state/config.ts
import { fromJSONFile } from "@mrspartak/config";
import * as z from "zod"
const config = await fromJSONFile({
path: ["../config/default.json", "../config/runtime.json"],
schema: z.object({
db: z.object({
host: z.string(),
port: z.number(),
username: z.string(),
password: z.string()
}),
app: z.object({
port: z.number().optional().default(3000)
})
}),
});
export default config
```
```ts
// file: index.ts
// Import your resolved configuration
import config from './state/config.js';
// Use the configuration in your application
import db from 'some-db-provider';
const dbClient = db(config.db); // Enjoy IntelliSense here!
```
## Using with .env configuration on back-end
> Libriaries that parse .env configuration files are rich with features, so no reason to write my own. But this library can still be used on top for validation and IntelliSense purposes.
```ts
// file: state/config.ts
import { fromObject } from "@mrspartak/config";
import * as z from "zod"
const schema = z
.object({
NODE_ENV: z.enum(["development", "production"]),
DB_HOST: z.string(),
DB_PORT: z.number(),
DB_USER: z.string(),
DB_PASSWORD: z.string(),
APP_PORT: z.number().default(3000),
})
.transform((data) => ({
environment: data.NODE_ENV,
port: data.APP_PORT,
db: {
host: data.DB_HOST,
port: data.DB_PORT,
user: data.DB_USER,
password: data.DB_PASSWORD,
},
}));
const config = await fromObject({
data: process.env,
schema
})
export default config
```
```ts
// file index.ts
import 'dotenv/config'
// ! Configuration must be loaded after dotenv so it will populate process.env
import config from './state/config.js';
// Use the configuration in your application
import db from 'some-db-provider';
const dbClient = db(config.db); // Enjoy IntelliSense here!
```
## Using on front-end
> There is a separate build, that trims Node APIs for usage on front-end. Because this library is mostly build to improve DX, I see no reason to bundle it for usage on front-ends without a bundler (vite, webpack...)
> It supports both build-time and run-time configurations
### Build-time front-end configuration
```ts
// file: state/config.ts
import { fromObject } from "@mrspartak/config/web"; // a separate build of the library
import * as z from "zod"
const schema = z
.object({
API_URL: z.string(),
})
const config = await fromObject({
data: import.meta.env, // example with vite
schema
})
export default config
```
### Run-time front-end configuration
```ts
// file: state/config.ts
import { fromURL } from "@mrspartak/config/web"; // a separate build of the library
import * as z from "zod"
const environment = import.meta.env.DEV ? "development" : "production"
const configPath = `/config/${environment}.json`
const schema = z
.object({
api_url: z.string(),
})
const config = await fromURL({
url: configPath, // will load a json from URL
schema
})
export default config
```
### Front-end usage
```tsx
// file main.tsx
import React from "react"
import ReactDOM from "react-dom/client"
import { ConfigProvider } from "@/context/ConfigContext"
import { Routes } from "@/routes"
async function main() {
// Can be build-time, run-time or even both
const config = await import("@/state/config");
ReactDOM.createRoot(document.getElementById("root")!).render(
)
}
main().catch(error => {
console.error("Mount error", error)
ReactDOM.createRoot(document.getElementById("root")!).render(
1. Try to reaload the page.
2. If doesn't help, please talk to developers, something went wrong.
})
```
API documentation is generated from TS declaration is avialable here: https://mrspartak.github.io/config/
## Contributing
I welcome contributions from the community! Whether it's improving the documentation, adding new features, or reporting bugs, please feel free to make a pull request or open an issue.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.