@vercel/config 0.0.21 → 0.0.23

package/README.md

@@ -13,10 +13,8 @@ npm install @vercel/config
 Create a `vercel.ts` file in your project root:
 
 ```typescript
-import { createRouter } from '@vercel/config';
-import type { VercelConfig } from '@vercel/config';
-
-const router = createRouter();
+import { routes, deploymentEnv } from '@vercel/config/v1';
+import type { VercelConfig } from '@vercel/config/v1';
 
 export const config: VercelConfig = {
   buildCommand: 'npm run build',
@@ -24,25 +22,33 @@ export const config: VercelConfig = {
   
   rewrites: [
     // Simple rewrite
-    router.rewrite('/api/(.*)', 'https://backend.api.example.com/$1'),
+    routes.rewrite('/api/(.*)', 'https://backend.api.example.com/$1'),
+    
+    // Rewrite with transforms (no path params)
+    routes.rewrite('/(.*)', 'https://api.example.com/$1', {
+      requestHeaders: {
+        'authorization': `Bearer ${deploymentEnv('API_TOKEN')}`
+      }
+    }),
     
-    // Rewrite with transforms
-    router.rewrite('/users/:userId', 'https://api.example.com/users/$1', 
-      ({ userId, env }) => ({
+    // Type-safe path parameters with callback
+    routes.rewrite('/users/:userId/posts/:postId', 'https://api.example.com/users/$1/posts/$2', 
+      ({ userId, postId }) => ({
         requestHeaders: {
           'x-user-id': userId,
-          'authorization': `Bearer ${env.API_TOKEN}`
+          'x-post-id': postId,
+          'authorization': `Bearer ${deploymentEnv('API_KEY')}`
         }
       })
     )
   ],
   
   redirects: [
-    router.redirect('/old-docs', '/docs', { permanent: true })
+    routes.redirect('/old-docs', '/docs', { permanent: true })
   ],
 
   headers: [
-    router.cacheControl('/static/(.*)', {
+    routes.cacheControl('/static/(.*)', {
       public: true,
       maxAge: '1 week',
       immutable: true
@@ -58,7 +64,9 @@ export const config: VercelConfig = {
 ## Features
 
 - **Type-safe configuration** - Full TypeScript support with IDE autocomplete
-- **Readable syntax** - Helper methods like `router.redirect()`, `router.rewrite()`, `router.header()`
+- **Type-safe path parameters** - Extract `:userId` from patterns with full IntelliSense
+- **Deployment environment variables** - Use `deploymentEnv()` for Vercel project env vars
+- **Readable syntax** - Helper methods like `routes.redirect()`, `routes.rewrite()`, `routes.header()`
 - **Transforms** - Modify request/response headers and query parameters on the fly
 - **Conditions** - Advanced routing with `has` and `missing` conditions
 - **CLI tools** - `compile` and `validate` commands for development

package/dist/router.d.ts

@@ -1,21 +1,35 @@
 import type { Redirect, Rewrite } from './types';
 /**
- * Helper function to reference a path parameter in transforms.
- * Path parameters are extracted from the route pattern (e.g., :userId).
+ * Type utility to extract path parameter names from a route pattern string.
+ * Supports :paramName syntax used in path-to-regexp patterns.
  *
  * @example
- * param('userId') // Returns '$userId'
+ * ExtractPathParams<'/users/:userId/posts/:postId'> // 'userId' | 'postId'
+ * ExtractPathParams<'/api/(.*)'> // never
  */
-export declare function param(name: string): string;
+type ExtractPathParams<T extends string> = T extends `${string}:${infer Param}/${infer Rest}` ? (Param extends `${infer P}(${string}` ? P : Param) | ExtractPathParams<`/${Rest}`> : T extends `${string}:${infer Param}` ? Param extends `${infer P}(${string}` ? P : Param : never;
 /**
- * Helper function to reference a runtime environment variable in transforms.
- * These are environment variables that get resolved at request time by Vercel's routing layer,
- * not at build time.
+ * Creates an object type where keys are the extracted path parameter names
+ * and values are strings (the resolved $paramName values).
+ */
+type PathParams<T extends string> = {
+    [K in ExtractPathParams<T>]: string;
+};
+/**
+ * Helper function to reference a Vercel project environment variable.
+ * These are placeholders that get resolved at request time by Vercel's routing layer.
+ * They are set per-deployment and don't change until you redeploy.
  *
  * @example
- * runtimeEnv('BEARER_TOKEN') // Returns '$BEARER_TOKEN'
+ * // Usage in rewrites with type-safe path params:
+ * routes.rewrite('/users/:userId', 'https://api.example.com/$1', ({ userId }) => ({
+ *   requestHeaders: {
+ *     'x-user-id': userId,
+ *     'authorization': `Bearer ${deploymentEnv('API_KEY')}`
+ *   }
+ * }))
  */
-export declare function runtimeEnv(name: string): string;
+export declare function deploymentEnv(name: string): string;
 /**
  * Template literal type for durations recognized by pretty-cache-header.
  *
@@ -264,6 +278,8 @@ export interface Route {
     status?: number;
     /** Headers to set (alternative to using transforms) */
     headers?: Record<string, string>;
+    /** Environment variables referenced in dest or transforms */
+    env?: string[];
 }
 /**
  * Represents a single HTTP header key/value pair.
@@ -489,11 +505,6 @@ export declare class Router {
      * extractPathParams('/users/:userId/posts/:postId') // Returns ['userId', 'postId']
      */
     private extractPathParams;
-    /**
-     * Creates a Proxy object that tracks environment variable accesses.
-     * Returns both the proxy and a set of accessed environment variable names.
-     */
-    private createEnvProxy;
     /**
      * Creates a rewrite rule. Returns either a Rewrite object (simple case) or Route with transforms.
      *
@@ -501,27 +512,42 @@ export declare class Router {
      *    // Simple rewrite
      *    router.rewrite('/api/(.*)', 'https://old-on-prem.com/$1')
      *
-     *    // With transforms
-     *    router.rewrite('/users/:userId', 'https://api.example.com/users/$1', ({userId, env}) => ({
-     *      requestHeaders: { 'x-user-id': userId }
+     *    // With transforms but no path params
+     *    router.rewrite('/(.*)', 'https://api.example.com/$1', {
+     *      requestHeaders: {
+     *        'authorization': `Bearer ${deploymentEnv('API_KEY')}`
+     *      }
+     *    })
+     *
+     *    // With type-safe path params
+     *    router.rewrite('/users/:userId', 'https://api.example.com/users/$1', ({ userId }) => ({
+     *      requestHeaders: {
+     *        'x-user-id': userId,
+     *        'authorization': `Bearer ${deploymentEnv('API_KEY')}`
+     *      }
      *    }))
+     *
+     *    // With conditions only
+     *    router.rewrite('/admin/(.*)', 'https://admin.example.com/$1', {
+     *      has: [{ type: 'header', key: 'x-admin-token' }]
+     *    })
      * @internal Can return Route with transforms internally
      */
-    rewrite(source: string, destination: string, optionsOrCallback?: {
+    rewrite<T extends string>(source: T, destination: string): Rewrite | Route;
+    rewrite<T extends string>(source: T, destination: string, callback: (params: PathParams<T>) => {
         has?: Condition[];
         missing?: Condition[];
         requestHeaders?: Record<string, string | string[]>;
         responseHeaders?: Record<string, string | string[]>;
         requestQuery?: Record<string, string | string[]>;
-    } | ((params: Record<string, string> & {
-        env: any;
-    }) => {
+    }): Rewrite | Route;
+    rewrite<T extends string>(source: T, destination: string, options: ({
         has?: Condition[];
         missing?: Condition[];
         requestHeaders?: Record<string, string | string[]>;
         responseHeaders?: Record<string, string | string[]>;
         requestQuery?: Record<string, string | string[]>;
-    })): Rewrite | Route;
+    }) & Record<never, never>): Rewrite | Route;
     /**
      * Creates a redirect rule. Returns either a Redirect object (simple case) or Route with transforms.
      *
@@ -529,28 +555,44 @@ export declare class Router {
      *    // Simple redirect
      *    router.redirect('/old-path', '/new-path', { permanent: true })
      *
-     *    // With transforms
-     *    router.redirect('/users/:userId', '/new-users/$1', ({userId, env}) => ({
+     *    // With transforms but no path params
+     *    router.redirect('/old', '/new', {
      *      permanent: true,
-     *      requestHeaders: { 'x-user-id': userId }
+     *      requestHeaders: {
+     *        'x-api-key': deploymentEnv('API_KEY')
+     *      }
+     *    })
+     *
+     *    // With type-safe path params
+     *    router.redirect('/users/:userId', '/new-users/$1', ({ userId }) => ({
+     *      permanent: true,
+     *      requestHeaders: {
+     *        'x-user-id': userId,
+     *        'x-api-key': deploymentEnv('API_KEY')
+     *      }
      *    }))
+     *
+     *    // With conditions only
+     *    router.redirect('/dashboard/(.*)', '/login', {
+     *      missing: [{ type: 'cookie', key: 'auth-token' }]
+     *    })
      * @internal Can return Route with transforms internally
      */
-    redirect(source: string, destination: string, optionsOrCallback?: {
+    redirect<T extends string>(source: T, destination: string): Redirect | Route;
+    redirect<T extends string>(source: T, destination: string, callback: (params: PathParams<T>) => {
         permanent?: boolean;
         statusCode?: number;
         has?: Condition[];
         missing?: Condition[];
         requestHeaders?: Record<string, string | string[]>;
-    } | ((params: Record<string, string> & {
-        env: any;
-    }) => {
+    }): Redirect | Route;
+    redirect<T extends string>(source: T, destination: string, options: {
         permanent?: boolean;
         statusCode?: number;
         has?: Condition[];
         missing?: Condition[];
         requestHeaders?: Record<string, string | string[]>;
-    })): Redirect | Route;
+    }): Redirect | Route;
     /**
      * Creates a header rule matching the vercel.json schema.
      * @example
@@ -647,3 +689,4 @@ export declare function createRoutes(): Router;
  *   routes.redirect('/old', '/new');
  */
 export declare const routes: Router;
+export {};

package/dist/router.js

@@ -1,31 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.routes = exports.createRoutes = exports.Router = exports.runtimeEnv = exports.param = void 0;
+exports.routes = exports.createRoutes = exports.Router = exports.deploymentEnv = void 0;
 const pretty_cache_header_1 = require("pretty-cache-header");
 const validation_1 = require("./utils/validation");
 /**
- * Helper function to reference a path parameter in transforms.
- * Path parameters are extracted from the route pattern (e.g., :userId).
+ * Helper function to reference a Vercel project environment variable.
+ * These are placeholders that get resolved at request time by Vercel's routing layer.
+ * They are set per-deployment and don't change until you redeploy.
  *
  * @example
- * param('userId') // Returns '$userId'
+ * // Usage in rewrites with type-safe path params:
+ * routes.rewrite('/users/:userId', 'https://api.example.com/$1', ({ userId }) => ({
+ *   requestHeaders: {
+ *     'x-user-id': userId,
+ *     'authorization': `Bearer ${deploymentEnv('API_KEY')}`
+ *   }
+ * }))
  */
-function param(name) {
+function deploymentEnv(name) {
     return `$${name}`;
 }
-exports.param = param;
-/**
- * Helper function to reference a runtime environment variable in transforms.
- * These are environment variables that get resolved at request time by Vercel's routing layer,
- * not at build time.
- *
- * @example
- * runtimeEnv('BEARER_TOKEN') // Returns '$BEARER_TOKEN'
- */
-function runtimeEnv(name) {
-    return `$${name}`;
-}
-exports.runtimeEnv = runtimeEnv;
+exports.deploymentEnv = deploymentEnv;
 /**
  * Extract environment variable names from a string or array of strings
  * Returns env var names without the $ prefix, excluding path parameters
@@ -77,50 +72,15 @@ class Router {
         }
         return params;
     }
-    /**
-     * Creates a Proxy object that tracks environment variable accesses.
-     * Returns both the proxy and a set of accessed environment variable names.
-     */
-    createEnvProxy() {
-        const accessedVars = new Set();
-        const proxy = new Proxy({}, {
-            get(_target, prop) {
-                if (typeof prop === 'string') {
-                    accessedVars.add(prop);
-                    return `$${prop}`;
-                }
-                return undefined;
-            }
-        });
-        return { proxy, accessedVars };
-    }
-    /**
-     * Creates a rewrite rule. Returns either a Rewrite object (simple case) or Route with transforms.
-     *
-     * @example
-     *    // Simple rewrite
-     *    router.rewrite('/api/(.*)', 'https://old-on-prem.com/$1')
-     *
-     *    // With transforms
-     *    router.rewrite('/users/:userId', 'https://api.example.com/users/$1', ({userId, env}) => ({
-     *      requestHeaders: { 'x-user-id': userId }
-     *    }))
-     * @internal Can return Route with transforms internally
-     */
     rewrite(source, destination, optionsOrCallback) {
         this.validateSourcePattern(source);
         let options;
-        // Handle callback syntax
         if (typeof optionsOrCallback === 'function') {
             const pathParams = this.extractPathParams(source);
-            const { proxy: envProxy } = this.createEnvProxy();
-            // Create params object with path parameters as $paramName
             const paramsObj = {};
             for (const param of pathParams) {
                 paramsObj[param] = `$${param}`;
             }
-            paramsObj.env = envProxy;
-            // Call the callback to get options
             options = optionsOrCallback(paramsObj);
         }
         else {
@@ -183,13 +143,34 @@ class Router {
                 dest: destination,
                 transforms,
             };
+            if (has)
+                route.has = has;
+            if (missing)
+                route.missing = missing;
+            // Extract env vars from destination
+            const destEnvVars = extractEnvVars(destination, pathParams);
+            if (destEnvVars.length > 0) {
+                route.env = destEnvVars;
+            }
+            return route;
+        }
+        // Simple rewrite without transforms - check if destination has env vars
+        const pathParams = this.extractPathParams(source);
+        const destEnvVars = extractEnvVars(destination, pathParams);
+        if (destEnvVars.length > 0) {
+            // Need Route format to include env field
+            const route = {
+                src: source,
+                dest: destination,
+                env: destEnvVars,
+            };
             if (has)
                 route.has = has;
             if (missing)
                 route.missing = missing;
             return route;
         }
-        // Simple rewrite without transforms
+        // Simple rewrite without transforms or env vars
         const rewrite = {
             source,
             destination,
@@ -200,34 +181,15 @@ class Router {
             rewrite.missing = missing;
         return rewrite;
     }
-    /**
-     * Creates a redirect rule. Returns either a Redirect object (simple case) or Route with transforms.
-     *
-     * @example
-     *    // Simple redirect
-     *    router.redirect('/old-path', '/new-path', { permanent: true })
-     *
-     *    // With transforms
-     *    router.redirect('/users/:userId', '/new-users/$1', ({userId, env}) => ({
-     *      permanent: true,
-     *      requestHeaders: { 'x-user-id': userId }
-     *    }))
-     * @internal Can return Route with transforms internally
-     */
     redirect(source, destination, optionsOrCallback) {
         this.validateSourcePattern(source);
         let options;
-        // Handle callback syntax
         if (typeof optionsOrCallback === 'function') {
             const pathParams = this.extractPathParams(source);
-            const { proxy: envProxy } = this.createEnvProxy();
-            // Create params object with path parameters as $paramName
             const paramsObj = {};
             for (const param of pathParams) {
                 paramsObj[param] = `$${param}`;
             }
-            paramsObj.env = envProxy;
-            // Call the callback to get options
             options = optionsOrCallback(paramsObj);
         }
         else {
@@ -259,13 +221,36 @@ class Router {
                 status: statusCode || (permanent ? 308 : 307),
                 transforms,
             };
+            if (has)
+                route.has = has;
+            if (missing)
+                route.missing = missing;
+            // Extract env vars from destination
+            const destEnvVars = extractEnvVars(destination, pathParams);
+            if (destEnvVars.length > 0) {
+                route.env = destEnvVars;
+            }
+            return route;
+        }
+        // Simple redirect without transforms - check if destination has env vars
+        const pathParams = this.extractPathParams(source);
+        const destEnvVars = extractEnvVars(destination, pathParams);
+        if (destEnvVars.length > 0) {
+            // Need Route format to include env field
+            const route = {
+                src: source,
+                dest: destination,
+                redirect: true,
+                status: statusCode || (permanent ? 308 : 307),
+                env: destEnvVars,
+            };
             if (has)
                 route.has = has;
             if (missing)
                 route.missing = missing;
             return route;
         }
-        // Simple redirect without transforms
+        // Simple redirect without transforms or env vars
         const redirect = {
             source,
             destination,

package/dist/types.d.ts

@@ -149,7 +149,7 @@ export interface Condition {
 }
 /**
  * Redirect matching vercel.json schema
- * Returned by router.redirect()
+ * Returned by routes.redirect()
  */
 export interface Redirect {
     source: string;
@@ -161,7 +161,7 @@ export interface Redirect {
 }
 /**
  * Rewrite matching vercel.json schema
- * Returned by router.rewrite()
+ * Returned by routes.rewrite()
  */
 export interface Rewrite {
     source: string;
@@ -171,7 +171,7 @@ export interface Rewrite {
 }
 /**
  * Header rule matching vercel.json schema
- * Returned by router.header() and router.cacheControl()
+ * Returned by routes.header() and routes.cacheControl()
  */
 export interface HeaderRule {
     source: string;

package/dist/v1/types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Type declarations for @vercel/config
+ *
+ * Usage:
+ * /// <reference types="@vercel/config/v1/types" />
+ */
+export type { VercelConfig, Framework, FunctionConfig, CronJob, GitDeploymentConfig, GitConfig, GithubConfig, ImageConfig, Header, Condition, Redirect, Rewrite, HeaderRule, RouteType, WildcardDomain, BuildConfig, BuildItem } from "../types";

package/dist/v1/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Type declarations for @vercel/config
+ *
+ * Usage:
+ * /// <reference types="@vercel/config/v1/types" />
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/config",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "description": "A TypeScript SDK for programmatically configuring Vercel projects",
   "bugs": {
     "url": "https://github.com/vercel/config/issues"
@@ -17,11 +17,17 @@
     "*": {
       "v1": [
         "dist/v1/index.d.ts"
+      ],
+      "v1/types": [
+        "dist/v1/types.d.ts"
       ]
     }
   },
   "exports": {
-    "./v1": "./dist/v1/index.js"
+    "./v1": "./dist/v1/index.js",
+    "./v1/types": {
+      "types": "./dist/v1/types.d.ts"
+    }
   },
   "bin": {
     "@vercel/config": "./dist/cli.js"