@lacspace/env 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +91 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# @lacspace/env
|
|
4
|
+
|
|
5
|
+
**Typed, validated environment variables — fail fast at boot, not in production.**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/@lacspace/env)
|
|
8
|
+
[](https://packagephobia.com/result?p=@lacspace/env)
|
|
9
|
+
[](https://bundlephobia.com/package/@lacspace/env)
|
|
10
|
+
[](https://www.npmjs.com/package/@lacspace/env)
|
|
11
|
+
[](https://github.com/lacspace/npm-packages/blob/main/LICENSE)
|
|
12
|
+
|
|
13
|
+
</div>
|
|
14
|
+
|
|
15
|
+
> Declare a schema, validate `process.env` once at startup, and get a **typed, frozen** object. Missing or malformed variables throw **one clear error listing everything wrong** — so a bad deploy fails immediately instead of 500-ing at 2am. A zero-dependency [t3-env](https://env.t3.gg) / [envalid](https://github.com/af/envalid) alternative.
|
|
16
|
+
|
|
17
|
+
- 🔒 Types inferred from the schema — `env.PORT` is a `number`, guaranteed present
|
|
18
|
+
- 💥 Fail-fast with an aggregated, readable error
|
|
19
|
+
- 🧰 Validators: `str` · `num` · `int` · `port` · `bool` · `url` · `email` · `oneOf` · `json`
|
|
20
|
+
- 🎚️ `default`, `optional`, `min`/`max` per field
|
|
21
|
+
- ⚡ Zero dependencies · 🌍 isomorphic · 📦 ESM + CJS · fully typed
|
|
22
|
+
|
|
23
|
+
## Install
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
npm install @lacspace/env # or pnpm add / yarn add / bun add
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Define once, use everywhere
|
|
30
|
+
|
|
31
|
+
```ts
|
|
32
|
+
// env.ts
|
|
33
|
+
import { createEnv, str, port, url, bool, oneOf } from "@lacspace/env";
|
|
34
|
+
|
|
35
|
+
export const env = createEnv({
|
|
36
|
+
NODE_ENV: oneOf(["development", "production", "test"], { default: "development" }),
|
|
37
|
+
PORT: port({ default: 3000 }),
|
|
38
|
+
DATABASE_URL: url(),
|
|
39
|
+
SMTP_HOST: str(),
|
|
40
|
+
SMTP_PORT: port({ default: 587 }),
|
|
41
|
+
DEBUG: bool({ default: false }),
|
|
42
|
+
ADMIN_EMAILS: str({ optional: true }),
|
|
43
|
+
});
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
```ts
|
|
47
|
+
import { env } from "./env";
|
|
48
|
+
|
|
49
|
+
env.PORT; // number — 3000 unless set
|
|
50
|
+
env.DEBUG; // boolean
|
|
51
|
+
env.NODE_ENV; // "development" | "production" | "test"
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
If `DATABASE_URL` is missing and `SMTP_PORT` is `"abc"`, startup throws:
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
EnvError: Invalid environment variables:
|
|
58
|
+
• "DATABASE_URL" is required but was not set
|
|
59
|
+
• "SMTP_PORT" must be a number, got "abc"
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Validators
|
|
63
|
+
|
|
64
|
+
| Validator | Parses to | Options |
|
|
65
|
+
| --- | --- | --- |
|
|
66
|
+
| `str(opts?)` | string | `default`, `optional`, `allowEmpty` |
|
|
67
|
+
| `num` / `int` | number | `default`, `optional`, `min`, `max` |
|
|
68
|
+
| `port(opts?)` | number (1–65535) | `default`, `optional` |
|
|
69
|
+
| `bool(opts?)` | boolean | accepts `true/1/yes/on`, `false/0/no/off` |
|
|
70
|
+
| `url` / `email` | validated string | `default`, `optional` |
|
|
71
|
+
| `oneOf(values, opts?)` | union of literals | `default`, `optional` |
|
|
72
|
+
| `json<T>(opts?)` | parsed JSON | `default`, `optional` |
|
|
73
|
+
|
|
74
|
+
## Not just `process.env`
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
createEnv(schema, import.meta.env); // Vite
|
|
78
|
+
createEnv(schema, Deno.env.toObject());
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## The Lacspace WebKit
|
|
82
|
+
|
|
83
|
+
| Package | For |
|
|
84
|
+
| --- | --- |
|
|
85
|
+
| [`@lacspace/seo`](https://www.npmjs.com/package/@lacspace/seo) | Metadata & JSON-LD |
|
|
86
|
+
| **`@lacspace/env`** | Typed env variables (this package) |
|
|
87
|
+
| [`@lacspace/rate-limit`](https://www.npmjs.com/package/@lacspace/rate-limit) | Rate limiting |
|
|
88
|
+
| [`@lacspace/otp`](https://www.npmjs.com/package/@lacspace/otp) | TOTP/HOTP 2FA |
|
|
89
|
+
| [`@lacspace/next`](https://www.npmjs.com/package/@lacspace/next) | Next.js SDK integration |
|
|
90
|
+
|
|
91
|
+
<div align="center"><sub>Built with care by <a href="https://lacspace.com">Lacspace</a> · MIT licensed · <a href="https://github.com/lacspace/npm-packages">source</a></sub></div>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@lacspace/env",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"description": "Typed, validated environment variables — declare a schema, validate process.env at boot, get a typed frozen object or a clear fail-fast error. A zero-dependency t3-env / envalid alternative.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.cjs",
|