npm - @dyanet/nextjs-config-aws - Versions diffs - 1.0.0-beta.1 - Mend

@dyanet/nextjs-config-aws 1.0.0-beta.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.

Files changed (50) hide show

package/README.md +458 -0
package/dist/cjs/client/env.js +104 -0
package/dist/cjs/client/env.js.map +1 -0
package/dist/cjs/client/index.js +15 -0
package/dist/cjs/client/index.js.map +1 -0
package/dist/cjs/components/index.js +11 -0
package/dist/cjs/components/index.js.map +1 -0
package/dist/cjs/components/public-env-script.js +145 -0
package/dist/cjs/components/public-env-script.js.map +1 -0
package/dist/cjs/index.js +46 -0
package/dist/cjs/index.js.map +1 -0
package/dist/cjs/server/config-provider.js +99 -0
package/dist/cjs/server/config-provider.js.map +1 -0
package/dist/cjs/server/get-config.js +153 -0
package/dist/cjs/server/get-config.js.map +1 -0
package/dist/cjs/server/index.js +17 -0
package/dist/cjs/server/index.js.map +1 -0
package/dist/esm/client/env.js +98 -0
package/dist/esm/client/env.js.map +1 -0
package/dist/esm/client/index.js +8 -0
package/dist/esm/client/index.js.map +1 -0
package/dist/esm/components/index.js +5 -0
package/dist/esm/components/index.js.map +1 -0
package/dist/esm/components/public-env-script.js +107 -0
package/dist/esm/components/public-env-script.js.map +1 -0
package/dist/esm/index.js +15 -0
package/dist/esm/index.js.map +1 -0
package/dist/esm/server/config-provider.js +95 -0
package/dist/esm/server/config-provider.js.map +1 -0
package/dist/esm/server/get-config.js +145 -0
package/dist/esm/server/get-config.js.map +1 -0
package/dist/esm/server/index.js +6 -0
package/dist/esm/server/index.js.map +1 -0
package/dist/types/client/env.d.ts +116 -0
package/dist/types/client/env.d.ts.map +1 -0
package/dist/types/client/index.d.ts +8 -0
package/dist/types/client/index.d.ts.map +1 -0
package/dist/types/components/index.d.ts +5 -0
package/dist/types/components/index.d.ts.map +1 -0
package/dist/types/components/public-env-script.d.ts +91 -0
package/dist/types/components/public-env-script.d.ts.map +1 -0
package/dist/types/index.d.ts +13 -0
package/dist/types/index.d.ts.map +1 -0
package/dist/types/server/config-provider.d.ts +80 -0
package/dist/types/server/config-provider.d.ts.map +1 -0
package/dist/types/server/get-config.d.ts +86 -0
package/dist/types/server/get-config.d.ts.map +1 -0
package/dist/types/server/index.d.ts +6 -0
package/dist/types/server/index.d.ts.map +1 -0
package/package.json +90 -0

package/README.md ADDED Viewed

@@ -0,0 +1,458 @@
+# @dyanet/nextjs-config-aws
+Next.js adapter for AWS configuration management. A thin wrapper around [@dyanet/config-aws](../config-aws) that provides server-side configuration loading, React context providers, and runtime environment variable support.
+## Features
+- **Server Components** - Load configuration in Server Components and API routes
+- **Runtime Environment Variables** - Deploy the same build to different environments
+- **Caching** - Avoid repeated AWS API calls during request handling
+- **React Context** - Share configuration across your component tree
+- **Type Safety** - Full TypeScript support with Zod schema validation
+- **AWS Services** - Load configuration from Secrets Manager, SSM Parameter Store, S3
+## Installation
+```bash
+npm install @dyanet/nextjs-config-aws
+```
+### Peer Dependencies
+```bash
+npm install next react
+```
+For AWS services, install the SDK clients you need:
+```bash
+# For Secrets Manager
+npm install @aws-sdk/client-secrets-manager
+# For SSM Parameter Store
+npm install @aws-sdk/client-ssm
+# For S3
+npm install @aws-sdk/client-s3
+# For schema validation
+npm install zod
+```
+## Quick Start
+### Server-Side Configuration
+```typescript
+// app/page.tsx (Server Component)
+import { getConfig, EnvironmentLoader, SecretsManagerLoader } from '@dyanet/nextjs-config-aws';
+import { z } from 'zod';
+const schema = z.object({
+  DATABASE_URL: z.string(),
+  API_KEY: z.string(),
+});
+export default async function Page() {
+  const config = await getConfig({
+    schema,
+    loaders: [
+      new EnvironmentLoader(),
+      new SecretsManagerLoader({ secretName: '/my-app/config' }),
+    ],
+    precedence: 'aws-first',
+  });
+  return <div>Connected to: {config.DATABASE_URL}</div>;
+}
+```
+### Runtime Environment Variables
+```tsx
+// app/layout.tsx
+import { PublicEnvScript } from '@dyanet/nextjs-config-aws';
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <head>
+        <PublicEnvScript
+          publicVars={['API_URL', 'APP_NAME', 'FEATURE_FLAGS']}
+        />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+```tsx
+// app/components/client-component.tsx
+'use client';
+import { env } from '@dyanet/nextjs-config-aws';
+export function ClientComponent() {
+  const apiUrl = env('API_URL');
+  const appName = env('APP_NAME', 'My App');
+  return <div>API: {apiUrl}, App: {appName}</div>;
+}
+```
+## Server-Side API
+### getConfig()
+Load configuration in Server Components, API routes, or server actions:
+```typescript
+import { getConfig, EnvironmentLoader, SecretsManagerLoader } from '@dyanet/nextjs-config-aws';
+import { z } from 'zod';
+const schema = z.object({
+  DATABASE_URL: z.string(),
+  API_KEY: z.string(),
+  PORT: z.coerce.number().default(3000),
+});
+// In a Server Component
+export default async function Page() {
+  const config = await getConfig({
+    schema,
+    loaders: [
+      new EnvironmentLoader({ prefix: 'APP_' }),
+      new SecretsManagerLoader({ secretName: '/my-app/secrets' }),
+    ],
+    precedence: 'aws-first',
+    cache: true,        // Enable caching (default: true)
+    cacheTTL: 60000,    // Cache for 1 minute (default)
+  });
+  return <div>{config.DATABASE_URL}</div>;
+}
+```
+#### Options
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `schema` | `ZodType<T>` | `undefined` | Zod schema for validation |
+| `loaders` | `ConfigLoader[]` | `[]` | Array of configuration loaders |
+| `precedence` | `PrecedenceStrategy` | `'aws-first'` | Precedence strategy |
+| `cache` | `boolean` | `true` | Enable caching |
+| `cacheTTL` | `number` | `60000` | Cache TTL in milliseconds |
+| `enableLogging` | `boolean` | `false` | Enable logging |
+### Cache Management
+```typescript
+import { clearConfigCache, getConfigCacheSize, invalidateConfig } from '@dyanet/nextjs-config-aws';
+// Clear all cached configurations
+clearConfigCache();
+// Get number of cached configurations
+const size = getConfigCacheSize();
+// Invalidate a specific configuration
+invalidateConfig({ loaders: [...], precedence: 'aws-first' });
+```
+### createConfigProvider()
+Create a typed React context provider for sharing configuration:
+```typescript
+// lib/config.ts
+import { createConfigProvider, getConfig } from '@dyanet/nextjs-config-aws';
+import { z } from 'zod';
+const schema = z.object({
+  DATABASE_URL: z.string(),
+  API_KEY: z.string(),
+});
+export type AppConfig = z.infer<typeof schema>;
+// Create typed provider and hook
+export const { ConfigProvider, useConfig } = createConfigProvider<AppConfig>();
+export { schema };
+```
+```tsx
+// app/layout.tsx
+import { ConfigProvider, schema } from '@/lib/config';
+import { getConfig, EnvironmentLoader } from '@dyanet/nextjs-config-aws';
+export default async function RootLayout({ children }) {
+  const config = await getConfig({
+    schema,
+    loaders: [new EnvironmentLoader()],
+  });
+  return (
+    <html>
+      <body>
+        <ConfigProvider config={config}>
+          {children}
+        </ConfigProvider>
+      </body>
+    </html>
+  );
+}
+```
+```tsx
+// app/components/my-component.tsx
+'use client';
+import { useConfig } from '@/lib/config';
+export function MyComponent() {
+  const config = useConfig();
+  return <div>API Key: {config.API_KEY}</div>;
+}
+```
+## Runtime Environment Variables
+### PublicEnvScript
+Server component that injects environment variables into the client:
+```tsx
+import { PublicEnvScript } from '@dyanet/nextjs-config-aws';
+// In your root layout
+<PublicEnvScript
+  publicVars={['API_URL', 'APP_NAME']}  // Explicit allowlist
+  variableName="__ENV"                   // Global variable name (default)
+  nonce={cspNonce}                       // CSP nonce (optional)
+/>
+// Or use prefix filtering
+<PublicEnvScript
+  publicPrefix="PUBLIC_"                 // Include all PUBLIC_* vars
+/>
+```
+#### Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `publicVars` | `string[]` | `undefined` | Explicit list of variables to expose |
+| `publicPrefix` | `string` | `undefined` | Prefix to filter variables |
+| `variableName` | `string` | `'__ENV'` | Global variable name on window |
+| `nonce` | `string` | `undefined` | CSP nonce for script tag |
+**Security Note:** Only expose variables that are safe for public access. Never expose secrets, API keys, or sensitive data.
+### Client-Side Access
+```typescript
+'use client';
+import { env, envFrom, getAllEnv, hasEnv } from '@dyanet/nextjs-config-aws';
+// Get a variable (returns undefined if not found)
+const apiUrl = env('API_URL');
+// Get with default value
+const appName = env('APP_NAME', 'My App');
+// Get from custom variable name
+const customVar = envFrom('__MY_ENV', 'API_URL');
+// Get all variables
+const allEnv = getAllEnv();
+// Check if variable exists
+if (hasEnv('FEATURE_FLAG')) {
+  // Feature is enabled
+}
+```
+## App Router Examples
+### Server Component
+```tsx
+// app/dashboard/page.tsx
+import { getConfig, EnvironmentLoader, SSMParameterStoreLoader } from '@dyanet/nextjs-config-aws';
+import { z } from 'zod';
+const schema = z.object({
+  DATABASE_URL: z.string(),
+  FEATURE_FLAGS: z.string().transform(s => JSON.parse(s)),
+});
+export default async function DashboardPage() {
+  const config = await getConfig({
+    schema,
+    loaders: [
+      new EnvironmentLoader(),
+      new SSMParameterStoreLoader({ parameterPath: '/app/config' }),
+    ],
+  });
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      <p>Features: {JSON.stringify(config.FEATURE_FLAGS)}</p>
+    </div>
+  );
+}
+```
+### API Route
+```typescript
+// app/api/config/route.ts
+import { NextResponse } from 'next/server';
+import { getConfig, EnvironmentLoader } from '@dyanet/nextjs-config-aws';
+import { z } from 'zod';
+const schema = z.object({
+  API_VERSION: z.string(),
+  MAX_REQUESTS: z.coerce.number(),
+});
+export async function GET() {
+  const config = await getConfig({
+    schema,
+    loaders: [new EnvironmentLoader()],
+  });
+  return NextResponse.json({
+    version: config.API_VERSION,
+    maxRequests: config.MAX_REQUESTS,
+  });
+}
+```
+### Server Action
+```typescript
+// app/actions.ts
+'use server';
+import { getConfig, SecretsManagerLoader } from '@dyanet/nextjs-config-aws';
+import { z } from 'zod';
+const schema = z.object({
+  API_KEY: z.string(),
+});
+export async function fetchData() {
+  const config = await getConfig({
+    schema,
+    loaders: [new SecretsManagerLoader({ secretName: '/app/secrets' })],
+  });
+  const response = await fetch('https://api.example.com/data', {
+    headers: { 'Authorization': `Bearer ${config.API_KEY}` },
+  });
+  return response.json();
+}
+```
+## Pages Router Examples
+### getServerSideProps
+```typescript
+// pages/dashboard.tsx
+import { getConfig, EnvironmentLoader } from '@dyanet/nextjs-config-aws';
+import { z } from 'zod';
+import type { GetServerSideProps } from 'next';
+const schema = z.object({
+  API_URL: z.string(),
+});
+export const getServerSideProps: GetServerSideProps = async () => {
+  const config = await getConfig({
+    schema,
+    loaders: [new EnvironmentLoader()],
+  });
+  return {
+    props: {
+      apiUrl: config.API_URL,
+    },
+  };
+};
+export default function Dashboard({ apiUrl }: { apiUrl: string }) {
+  return <div>API URL: {apiUrl}</div>;
+}
+```
+### API Route (Pages Router)
+```typescript
+// pages/api/config.ts
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { getConfig, EnvironmentLoader } from '@dyanet/nextjs-config-aws';
+import { z } from 'zod';
+const schema = z.object({
+  APP_VERSION: z.string(),
+});
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  const config = await getConfig({
+    schema,
+    loaders: [new EnvironmentLoader()],
+  });
+  res.json({ version: config.APP_VERSION });
+}
+```
+## Re-exported Types
+All types from `@dyanet/config-aws` are re-exported:
+```typescript
+import {
+  // Loaders
+  EnvironmentLoader,
+  EnvFileLoader,
+  S3Loader,
+  SecretsManagerLoader,
+  SSMParameterStoreLoader,
+  // ConfigManager
+  ConfigManager,
+  // Error classes
+  ConfigurationError,
+  ValidationError,
+  AWSServiceError,
+  ConfigurationLoadError,
+  MissingConfigurationError,
+  // Utilities
+  ConfigValidationUtil,
+  EnvFileParser,
+  // Types
+  ConfigLoader,
+  ConfigManagerOptions,
+  LoaderPrecedence,
+  VerboseOptions,
+} from '@dyanet/nextjs-config-aws';
+```
+## Related Packages
+- **[@dyanet/config-aws](../config-aws)** - Framework-agnostic core library
+- **[@dyanet/nestjs-config-aws](../nestjs-config-aws)** - NestJS adapter
+## License
+MIT

package/dist/cjs/client/env.js ADDED Viewed

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Client-side environment variable access for Next.js applications.
+ *
+ * This module provides a function to read runtime environment variables
+ * that were injected by the PublicEnvScript server component.
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ *
+ * import { env } from '@dyanet/nextjs-config-aws/client';
+ *
+ * function MyComponent() {
+ *   const apiUrl = env('API_URL');
+ *   const appName = env('APP_NAME', 'Default App');
+ *
+ *   return <div>API: {apiUrl}, App: {appName}</div>;
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.env = env;
+exports.envFrom = envFrom;
+exports.getAllEnv = getAllEnv;
+exports.hasEnv = hasEnv;
+/**
+ * Default variable name used by PublicEnvScript.
+ */
+const DEFAULT_VARIABLE_NAME = '__ENV';
+/**
+ * Gets the environment variables object from the window.
+ *
+ * @param variableName - The global variable name to read from
+ * @returns The environment variables object, or an empty object if not found
+ */
+function getEnvObject(variableName = DEFAULT_VARIABLE_NAME) {
+    if (typeof window === 'undefined') {
+        // Server-side or during SSR - return empty object
+        return {};
+    }
+    const envObj = window[variableName];
+    if (envObj && typeof envObj === 'object' && !Array.isArray(envObj)) {
+        return envObj;
+    }
+    return {};
+}
+/**
+ * Implementation of the env function.
+ */
+function env(key, defaultValue) {
+    const envObj = getEnvObject();
+    const value = envObj[key];
+    if (value !== undefined) {
+        return value;
+    }
+    return defaultValue;
+}
+/**
+ * Implementation of the envFrom function.
+ */
+function envFrom(variableName, key, defaultValue) {
+    const envObj = getEnvObject(variableName);
+    const value = envObj[key];
+    if (value !== undefined) {
+        return value;
+    }
+    return defaultValue;
+}
+/**
+ * Gets all runtime environment variables.
+ *
+ * @param variableName - The global variable name to read from (default: '__ENV')
+ * @returns A copy of all environment variables
+ *
+ * @example
+ * ```ts
+ * const allEnv = getAllEnv();
+ * console.log(allEnv); // { API_URL: '...', APP_NAME: '...' }
+ * ```
+ */
+function getAllEnv(variableName = DEFAULT_VARIABLE_NAME) {
+    return { ...getEnvObject(variableName) };
+}
+/**
+ * Checks if a runtime environment variable exists.
+ *
+ * @param key - The environment variable name
+ * @param variableName - The global variable name to read from (default: '__ENV')
+ * @returns True if the variable exists, false otherwise
+ *
+ * @example
+ * ```ts
+ * if (hasEnv('FEATURE_FLAG')) {
+ *   // Feature is enabled
+ * }
+ * ```
+ */
+function hasEnv(key, variableName = DEFAULT_VARIABLE_NAME) {
+    const envObj = getEnvObject(variableName);
+    return key in envObj;
+}
+exports.default = env;
+//# sourceMappingURL=env.js.map

package/dist/cjs/client/env.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"env.js","sourceRoot":"","sources":["../../../src/client/env.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;AA0EH,kBASC;AAgCD,0BASC;AAcD,8BAEC;AAgBD,wBAGC;AAnJD;;GAEG;AACH,MAAM,qBAAqB,GAAG,OAAO,CAAC;AAEtC;;;;;GAKG;AACH,SAAS,YAAY,CAAC,eAAuB,qBAAqB;IAChE,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,kDAAkD;QAClD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;IACpC,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnE,OAAO,MAAgC,CAAC;IAC1C,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC;AAoCD;;GAEG;AACH,SAAgB,GAAG,CAAI,GAAW,EAAE,YAAgB;IAClD,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAE1B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AA6BD;;GAEG;AACH,SAAgB,OAAO,CAAI,YAAoB,EAAE,GAAW,EAAE,YAAgB;IAC5E,MAAM,MAAM,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAE1B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,SAAS,CAAC,eAAuB,qBAAqB;IACpE,OAAO,EAAE,GAAG,YAAY,CAAC,YAAY,CAAC,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,MAAM,CAAC,GAAW,EAAE,eAAuB,qBAAqB;IAC9E,MAAM,MAAM,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;IAC1C,OAAO,GAAG,IAAI,MAAM,CAAC;AACvB,CAAC;AAED,kBAAe,GAAG,CAAC"}

package/dist/cjs/client/index.js ADDED Viewed

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Client-side exports for Next.js configuration management.
+ *
+ * These utilities are designed for use in client components ('use client')
+ * to access runtime environment variables injected by PublicEnvScript.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasEnv = exports.getAllEnv = exports.envFrom = exports.env = void 0;
+var env_1 = require("./env");
+Object.defineProperty(exports, "env", { enumerable: true, get: function () { return env_1.env; } });
+Object.defineProperty(exports, "envFrom", { enumerable: true, get: function () { return env_1.envFrom; } });
+Object.defineProperty(exports, "getAllEnv", { enumerable: true, get: function () { return env_1.getAllEnv; } });
+Object.defineProperty(exports, "hasEnv", { enumerable: true, get: function () { return env_1.hasEnv; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/client/index.js.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,6BAAwD;AAA/C,0FAAA,GAAG,OAAA;AAAE,8FAAA,OAAO,OAAA;AAAE,gGAAA,SAAS,OAAA;AAAE,6FAAA,MAAM,OAAA"}

package/dist/cjs/components/index.js ADDED Viewed

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Client-side components for Next.js configuration management.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateScriptContent = exports.filterEnvVars = exports.PublicEnvScript = void 0;
+var public_env_script_1 = require("./public-env-script");
+Object.defineProperty(exports, "PublicEnvScript", { enumerable: true, get: function () { return public_env_script_1.PublicEnvScript; } });
+Object.defineProperty(exports, "filterEnvVars", { enumerable: true, get: function () { return public_env_script_1.filterEnvVars; } });
+Object.defineProperty(exports, "generateScriptContent", { enumerable: true, get: function () { return public_env_script_1.generateScriptContent; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/components/index.js.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/components/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,yDAK6B;AAJ3B,oHAAA,eAAe,OAAA;AACf,kHAAA,aAAa,OAAA;AACb,0HAAA,qBAAqB,OAAA"}