{"_id":"next-public-env","_rev":"4-a0bd76fed0a53507bc71a824f136b3ef","name":"next-public-env","dist-tags":{"latest":"1.1.0"},"versions":{"0.1.0":{"name":"next-public-env","version":"0.1.0","keywords":["nextjs","react","zod"],"author":{"name":"alizeait"},"license":"MIT","_id":"next-public-env@0.1.0","maintainers":[{"name":"alizeait","email":"rassoali.arz@gmail.com"}],"dist":{"shasum":"9363c3ebb5c5d36b772a59a8992ffe1dbd0cea3b","tarball":"https://registry.npmjs.org/next-public-env/-/next-public-env-0.1.0.tgz","fileCount":8,"integrity":"sha512-6uYiOvq1A3Fns79QVrjrASkpGYMVJL+lOdALwpFPiBmQ1oJdsAaHzxjSyIEdc2wwVHiG5n0Hq+9q+UHwyPcaRQ==","signatures":[{"sig":"MEYCIQDFjHuw7BZUP0CU3qEJBS1fpPY57xNEEkFxCQgN3DvrPwIhAMdNQ+vco/D9w7HUDrEt9gYKSqOcKK4stz3oJH4+u1ym","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":13123},"type":"module","types":"./dist/server/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"node":"./dist/server/index.js","types":"./dist/server/index.d.ts","browser":"./dist/browser/index.js","default":"./dist/server/index.js"}},"gitHead":"d8682929713ef38c782729c2b9ab00febdc2b2a1","scripts":{"test":"vitest run","build":"tsup","test:e2e":"playwright test","test:watch":"vitest","check-types":"tsc --noEmit"},"_npmUser":{"name":"alizeait","email":"rassoali.arz@gmail.com"},"_npmVersion":"10.9.0","description":"Manage type-safe runtime environment variables in Next.js for both the server and client.","directories":{},"_nodeVersion":"22.12.0","dependencies":{"zod":"^3.25.0 || ^4.0.0"},"typesVersions":{"*":{"*":["./dist/server/index.d.ts"]}},"_hasShrinkwrap":false,"devDependencies":{"zod":"^3.25.0 || ^4.0.0","next":"^16.0.0","tsup":"^8.5.0","jsdom":"^27.0.1","react":"^19.2.0","oxlint":"^1.24.0","vitest":"^4.0.1","prettier":"^3.6.2","react-dom":"^19.2.0","typescript":"^5.9.3","@types/node":"^22.9.0","@types/react":"^19.2.2","@playwright/test":"^1.56.1","@testing-library/dom":"^10.4.1","@testing-library/react":"^16.3.0"},"peerDependencies":{"zod":"^3.25.0 || ^4.0.0","next":"^14.0.0 || ^15.0.0 || ^16.0.0","react":"^17.0.0 || ^18.0.0 || ^19.0.0"},"_npmOperationalInternal":{"tmp":"tmp/next-public-env_0.1.0_1761931181622_0.6075187551950487","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"next-public-env","version":"0.2.0","keywords":["nextjs","react","zod"],"author":{"name":"alizeait"},"license":"MIT","_id":"next-public-env@0.2.0","maintainers":[{"name":"alizeait","email":"rassoali.arz@gmail.com"}],"dist":{"shasum":"8c5bf21f2d99a96c4a084e4ad7992e880df77d80","tarball":"https://registry.npmjs.org/next-public-env/-/next-public-env-0.2.0.tgz","fileCount":8,"integrity":"sha512-WWD8Xy/GpXBXNEHJ930PwT8AZFY3YQfRYBev5AGYpgW8+1kx/HEgunR5RzlXP/tB9OgCWXiFupxB7vgN4wv9qQ==","signatures":[{"sig":"MEUCIEN8eiqqdT/xcpRcnLA7FAWZ7k4tCLEJAA8OAE/1EDoxAiEAxeEm5+iINOVrZmND0EGaqQxV5zPFvTx6OrD45Pq3+lA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":13370},"type":"module","types":"./dist/server/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"node":"./dist/server/index.js","types":"./dist/server/index.d.ts","browser":"./dist/browser/index.js","default":"./dist/server/index.js"}},"gitHead":"90c1590651f71570b2f588192519228293aa1d27","scripts":{"test":"vitest run","build":"tsup","test:e2e":"playwright test","test:watch":"vitest","check-types":"tsc --noEmit"},"_npmUser":{"name":"alizeait","email":"rassoali.arz@gmail.com"},"_npmVersion":"10.9.0","description":"Manage type-safe runtime environment variables in Next.js for both the server and client.","directories":{},"_nodeVersion":"22.12.0","dependencies":{"zod":"^3.25.0 || ^4.0.0"},"typesVersions":{"*":{"*":["./dist/server/index.d.ts"]}},"_hasShrinkwrap":false,"devDependencies":{"zod":"^3.25.0 || ^4.0.0","next":"^16.0.0","tsup":"^8.5.0","jsdom":"^27.0.1","react":"^19.2.0","oxlint":"^1.24.0","vitest":"^4.0.1","prettier":"^3.6.2","react-dom":"^19.2.0","typescript":"^5.9.3","@types/node":"^22.9.0","@types/react":"^19.2.2","@playwright/test":"^1.56.1","@testing-library/dom":"^10.4.1","@testing-library/react":"^16.3.0"},"peerDependencies":{"zod":"^3.25.0 || ^4.0.0","next":"^14.0.0 || ^15.0.0 || ^16.0.0","react":"^17.0.0 || ^18.0.0 || ^19.0.0"},"_npmOperationalInternal":{"tmp":"tmp/next-public-env_0.2.0_1761954341823_0.8140547994464458","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"next-public-env","version":"1.0.0","keywords":["nextjs","react","zod"],"author":{"name":"alizeait"},"license":"MIT","_id":"next-public-env@1.0.0","maintainers":[{"name":"alizeait","email":"rassoali.arz@gmail.com"}],"homepage":"https://github.com/alizeait/next-public-env#readme","bugs":{"url":"https://github.com/alizeait/next-public-env/issues"},"dist":{"shasum":"8a3a0f5c2c1117d56eb1655ed3a4e57f47776851","tarball":"https://registry.npmjs.org/next-public-env/-/next-public-env-1.0.0.tgz","fileCount":8,"integrity":"sha512-U+FEGBKFNUaxrhR+6RvHHRpPe+VllIpNkRoOaf8uJ/6k/OBm8oRAdsBK8B38WwGBqeGX6kno81tpjqZ6rDE8Fw==","signatures":[{"sig":"MEYCIQDtDAmknElqlbWo0bmhvIRyQyywHLhgGT/SEPwsLcAejgIhAP82y422rlIiTp+YDbUPQIJRKyBrVy0ud0VWp6dDWwjw","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":13630},"type":"module","types":"./dist/server/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"node":"./dist/server/index.js","types":"./dist/server/index.d.ts","browser":"./dist/browser/index.js","default":"./dist/server/index.js"}},"gitHead":"8e2c3f0c70addeb3b3a6db689634351e66cf3cb1","scripts":{"test":"vitest run","build":"tsup","test:e2e":"playwright test","test:watch":"vitest","check-types":"tsc --noEmit"},"_npmUser":{"name":"alizeait","email":"rassoali.arz@gmail.com"},"repository":{"url":"git+https://github.com/alizeait/next-public-env.git","type":"git"},"_npmVersion":"10.9.0","description":"Manage type-safe runtime environment variables in Next.js for both the server and the client.","directories":{},"_nodeVersion":"22.12.0","dependencies":{"zod":"^3.25.0 || ^4.0.0"},"typesVersions":{"*":{"*":["./dist/server/index.d.ts"]}},"_hasShrinkwrap":false,"devDependencies":{"zod":"^3.25.0 || ^4.0.0","next":"^16.0.0","tsup":"^8.5.0","jsdom":"^27.0.1","react":"^19.2.0","oxlint":"^1.24.0","vitest":"^4.0.1","prettier":"^3.6.2","react-dom":"^19.2.0","typescript":"^5.9.3","@types/node":"^22.9.0","@types/react":"^19.2.2","@playwright/test":"^1.56.1","@testing-library/dom":"^10.4.1","@testing-library/react":"^16.3.0"},"peerDependencies":{"zod":"^3.25.0 || ^4.0.0","next":"^14.0.0 || ^15.0.0 || ^16.0.0","react":"^17.0.0 || ^18.0.0 || ^19.0.0"},"_npmOperationalInternal":{"tmp":"tmp/next-public-env_1.0.0_1762043470846_0.8647208529270098","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"next-public-env","description":"Manage type-safe runtime environment variables in Next.js for both the server and the client.","version":"1.1.0","author":{"name":"alizeait"},"license":"MIT","type":"module","types":"./dist/server/index.d.ts","exports":{".":{"node":"./dist/server/index.js","browser":"./dist/browser/index.js","types":"./dist/server/index.d.ts","default":"./dist/server/index.js"}},"typesVersions":{"*":{"*":["./dist/server/index.d.ts"]}},"scripts":{"build":"tsup","test":"vitest run","test:watch":"vitest","test:e2e":"playwright test","check-types":"tsc --noEmit"},"peerDependencies":{"next":"^14.0.0 || ^15.0.0 || ^16.0.0","react":"^17.0.0 || ^18.0.0 || ^19.0.0","zod":"^3.25.0 || ^4.0.0"},"dependencies":{"zod":"^3.25.0 || ^4.0.0"},"devDependencies":{"@playwright/test":"^1.56.1","@testing-library/dom":"^10.4.1","@testing-library/react":"^16.3.0","@types/node":"^22.9.0","@types/react":"^19.2.2","jsdom":"^27.0.1","next":"^16.0.3","oxlint":"^1.24.0","prettier":"^3.6.2","react":"^19.2.0","react-dom":"^19.2.0","tsup":"^8.5.0","typescript":"^5.9.3","vitest":"^4.0.1","zod":"^3.25.0 || ^4.0.0"},"repository":{"type":"git","url":"git+https://github.com/alizeait/next-public-env.git"},"bugs":{"url":"https://github.com/alizeait/next-public-env/issues"},"homepage":"https://github.com/alizeait/next-public-env#readme","keywords":["nextjs","react","zod"],"engines":{"node":">=20.0.0"},"_id":"next-public-env@1.1.0","gitHead":"29a78118b2f41413ed2a4f349f16a28065e027e9","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-LNgnYoPLuJtCO8nXVGq8TXZ6A3Ndb1s7sQQTtaF+PnYXw+qoN02BTqxSjmK+Bm9AW2xpqxkbBF0UNT6is+ps6g==","shasum":"594c4fe66414c0f690ff759b9e02060092f5a2cc","tarball":"https://registry.npmjs.org/next-public-env/-/next-public-env-1.1.0.tgz","fileCount":8,"unpackedSize":15948,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICoy24E1yA1MklGTvT2DrNYiiI/0wuFGPp2hoGMKtMtWAiEAp9hkKTt6d322km8AA3Mf7xC+0ZuKfJFtz+Dpw/pOXak="}]},"_npmUser":{"name":"alizeait","email":"rassoali.arz@gmail.com"},"directories":{},"maintainers":[{"name":"alizeait","email":"rassoali.arz@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/next-public-env_1.1.0_1763909848379_0.17180701958345646"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-31T17:19:41.562Z","modified":"2025-11-23T14:57:28.769Z","0.1.0":"2025-10-31T17:19:41.809Z","0.2.0":"2025-10-31T23:45:42.037Z","1.0.0":"2025-11-02T00:31:11.051Z","1.1.0":"2025-11-23T14:57:28.570Z"},"bugs":{"url":"https://github.com/alizeait/next-public-env/issues"},"author":{"name":"alizeait"},"license":"MIT","homepage":"https://github.com/alizeait/next-public-env#readme","keywords":["nextjs","react","zod"],"repository":{"type":"git","url":"git+https://github.com/alizeait/next-public-env.git"},"description":"Manage type-safe runtime environment variables in Next.js for both the server and the client.","maintainers":[{"name":"alizeait","email":"rassoali.arz@gmail.com"}],"readme":"# Next.js Public Runtime Environment\n\n`next-public-env` is a lightweight utility that dynamically injects environment\nvariables into your Next.js application at *runtime* instead of just at build time.\n\n## The Problem\n\nNext.js's standard approach bakes environment variables into your application\nduring the build process through `NEXT_PUBLIC_` variables. This means you need a\nseparate build for each environment; one for development, another for staging,\nand yet another for production. This violates the \"build once, deploy many\"\nprinciple and creates unnecessary complexity in your deployment pipeline.\n\n## Features\n\n- **Type Safety & Validation:** Integrates with Zod for schema validation, type\n  coercion, and full TypeScript support.\n- **Error-Resilient:** Environment variables remain accessible even when pages\n  throw unhandled errors.\n- **Universal API:** Use the same `getPublicEnv()` function in both Server and\n  Client Components.\n- **Lightweight:** Adds only ~275 bytes to your client bundle.\n\n## Installation\n\nInstall it via your preferred package manager:\n\n```bash\nyarn add next-public-env\n```\n```bash\npnpm add next-public-env\n```\n```bash\nnpm install next-public-env\n```\n\n## Getting Started\n\n### 1. Define Your Environment Config\n\nCreate a file to configure your public environment variables (e.g.,\n`public-env.ts`).\n\n**Basic (Type-Safe):**\n```ts\n// public-env.ts\nimport { createPublicEnv } from 'next-public-env';\n\nexport const { getPublicEnv, PublicEnv } = createPublicEnv({\n  NODE_ENV: process.env.NODE_ENV,\n  API_URL: process.env.API_URL,\n  MAINTENANCE_MODE: process.env.MAINTENANCE_MODE === 'true',\n});\n```\n\n**With Zod Validation (Recommended):**\n```ts\n// public-env.ts\nimport { createPublicEnv } from 'next-public-env';\n\nexport const { getPublicEnv, PublicEnv } = createPublicEnv(\n  {\n    NODE_ENV: process.env.NODE_ENV,\n    API_URL: process.env.API_URL,\n    MAINTENANCE_MODE: process.env.MAINTENANCE_MODE,\n    PORT: process.env.PORT,\n  },\n  {\n    schema: (z) => ({\n      NODE_ENV: z.enum(['development', 'production', 'test']),\n      API_URL: z.string().url(),\n      MAINTENANCE_MODE: z.enum(['on', 'off']).default('off'),\n      PORT: z.coerce.number().default(3000), // Converts string to number\n    }),\n  }\n);\n```\n\n### 2. Add to Root Layout\n\nPlace `<PublicEnv />` in your root layout to make variables available\nclient-side:\n\n```tsx\n// app/layout.tsx\nimport { PublicEnv } from './public-env';\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\nreturn (\n    <html lang=\"en\">\n      <body>\n        <PublicEnv />\n        {children}\n      </body>\n    </html>\n  );\n}\n```\n\n### 3. Use Anywhere\n\nAccess your environment variables with full type safety:\n\n```tsx\n// Server Component\nimport { getPublicEnv } from './public-env';\n\nexport default function ServerPage() {\n  const env = getPublicEnv();\n  return <div>API URL: {env.API_URL}</div>;\n}\n\n// Client Component\n'use client';\nimport { getPublicEnv } from './public-env';\n\nexport function ClientComponent() {\n  const env = getPublicEnv();\n  return <div>API URL: {env.API_URL}</div>;\n}\n```\n\n## Rendering Behavior\n\n### Default: Dynamic Rendering\n\nWhen you use `getPublicEnv()` in a Server Component, that route automatically\nswitches to **dynamic rendering**. This ensures your environment variables are\nalways read fresh from the server at request time, rather than being cached at\nbuild time.\n\n### Advanced: Manual Rendering Control\n\nFor specific use cases, you can override this behavior using the\n`dynamicRendering` option. Set it to `'manual'` to disable the automatic\n`noStore()` call and take full control of your routes' rendering behavior.\n\n\n\n## Cache Components Support\n\nNext.js Cache Components (enabled via `cacheComponents: true` in\n`next.config.js`) prerender routes into a static HTML shell by default. This\nmeans that environment variables are read at build time, which defeats the\npurpose of `next-public-env`.\n\nTo ensure your environment variables are read at runtime, you must opt-out of\nthe static shell by making your component dynamic. You can do this by using any\n[runtime API](https://nextjs.org/docs/app/getting-started/cache-components#runtime-data)(like\n`headers()`, `cookies()`, etc.) or by using the `getPublicEnvAsync()` function\nprovided by this library which automatically calls `await connection()` to\nopt-out of the static shell.\n\n### Using `getPublicEnvAsync()`\n\n`getPublicEnvAsync()` is a helper function that automatically calls `await\nconnection()` to opt-out of the static shell and returns your environment\nvariables.\n\n> **Important:** Components using `getPublicEnvAsync()` (or any runtime API)\n> should be wrapped in a `<Suspense>` boundary to allow the rest of the page to be\n> prerendered.\n\n```tsx\nimport { Suspense } from 'react';\nimport { getPublicEnvAsync } from './public-env';\n\nasync function EnvComponent() {\n  const env = await getPublicEnvAsync();\n  return <div>API URL: {env.API_URL}</div>;\n}\n\nexport default function Page() {\n  return (\n    <div>\n      <h1>My Page</h1>\n      <Suspense fallback={<div>Loading env...</div>}>\n        <EnvComponent />\n      </Suspense>\n    </div>\n  );\n}\n```\n\n## API Reference\n\n### `createPublicEnv(publicEnv, options)`\n\nThis is the main function used to configure the library.\n\n#### **Parameters**\n\n| Parameter   | Type     | Required? | Description                                                                                                                                                        |\n| :---------- | :------- | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `publicEnv` | `object` | Yes       | An object that explicitly defines the variables and values to be made available. This acts as an allowlist, ensuring no other `process.env` variables are exposed. |\n| `options`   | `object` | No        | An optional object for advanced configuration like schema validation and rendering behavior.                                                                       |\n\n#### **Options Object Properties**\n\n| Property              | Type                      | Description                                                                                                                                                                                                                                                                                                                |\n| :-------------------- | :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `schema`              | `(z) => ZodObject`        | An optional function that receives the Zod library (`z`) as an argument and returns a Zod schema object. The keys in the schema must match the keys in your `publicEnv` object. Used for validation, type coercion, and setting defaults.                                                                                  |\n| `validateAtBuildStep` | `boolean`                 | If `true`, the library validates your `publicEnv` object against the schema during `next build`. Useful for failing builds early in CI/CD. **Default: `false`**.                                                                                                                                                           |\n| `dynamicRendering`    | `'auto'` \\| `'manual'`    | Controls the dynamic rendering behavior. `'auto'` (default) automatically opts-out of static rendering by calling `noStore()`. `'manual'` requires you to manage rendering behavior yourself. **Warning:** Using `manual` incorrectly can lead to undefined variables. **Default: `'auto'`**. |\n\n#### **Returns**\n\nThe function returns an object containing the `getPublicEnv` function and the\n`PublicEnv` component.\n\n| Property      | Type                | Description                                                                                                                             |\n| :------------ | :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------- |\n| `getPublicEnv`| `() => EnvObject`   | A function that returns your public environment variables. The return type is inferred from your `publicEnv` object and Zod schema.      |\n| `getPublicEnvAsync`| `() => Promise<EnvObject>` | An async function that returns your public environment variables and opts-out of static rendering by calling `await connection()`. |\n| `PublicEnv`   | `React.Component`   | A React component that must be rendered in your root layout to inject the environment variables for client-side access.               |","readmeFilename":"README.md"}