@vercel/config 0.0.14 → 0.0.17

package/README.md

@@ -1,6 +1,6 @@
 # @vercel/config
 
-TypeScript SDK for defining Vercel configuration programmatically.
+TypeScript SDK for programmatically defining Vercel configuration. Write type-safe routing rules and build configuration in TypeScript instead of JSON.
 
 ## Installation
 
@@ -8,338 +8,92 @@ TypeScript SDK for defining Vercel configuration programmatically.
 npm install @vercel/config
 ```
 
-## Usage
+## Quick Start
 
 Create a `vercel.ts` file in your project root:
 
 ```typescript
 import { createRouter } from '@vercel/config';
+import type { VercelConfig } from '@vercel/config';
 
 const router = createRouter();
 
-// Basic rewrite
-router.rewrite('/api/(.*)', 'https://backend.com/$1');
-
-// Rewrite with transforms
-router.rewrite('/users/:userId', 'https://api.example.com/users/$1', ({userId, env}) => ({
-  requestHeaders: {
-    'x-user-id': userId,
-    'authorization': `Bearer ${env.API_TOKEN}`
-  }
-}));
-
-// Redirects
-router.redirect('/old-docs', '/docs', { permanent: true });
-
-// Cache control
-router.cacheControl('/static/(.*)', {
-  public: true,
-  maxAge: '1 week',
-  immutable: true
-});
-
-// Global settings
-router.cleanUrls = true;
-router.trailingSlash = true;
-
-// Bulk redirects
-router.bulkRedirectsPath = './bulkRedirectsDemo.json';
-
-// Cron jobs
-router.cron('/api/cleanup', '0 0 * * *');
-
-export default router.getConfig();
-```
-
-## Automatic Compilation
-
-Your `vercel.ts` file is automatically compiled when you run:
-
-```bash
-vercel build   # For local builds
-vercel dev     # For local development  
-vercel deploy  # For deployment
-```
-
-The Vercel CLI automatically compiles `vercel.ts` to `.vercel/vercel.json` before building or deploying.
-
-## API Reference
-
-### `createRouter()`
-
-Creates a new router instance.
-
-### `router.rewrite(source, destination, options?)`
-
-Add a rewrite rule. Options can be an object or a callback function that receives path parameters and environment variables.
-
-```typescript
-// With callback for transforms
-router.rewrite('/users/:userId', 'https://api.example.com/users/$1', ({userId, env}) => ({
-  requestHeaders: {
-    'x-user-id': userId,
-    'authorization': `Bearer ${env.API_TOKEN}`
-  },
-  responseHeaders: {
-    'x-powered-by': 'My API'
-  },
-  requestQuery: {
-    'version': '2.0'
-  }
-}));
-
-// Simple rewrite without transforms
-router.rewrite('/api/(.*)', 'https://backend.com/$1');
-```
-
-### `router.redirect(source, destination, options?)`
-
-Add a redirect rule. Options include `permanent` and `statusCode`.
-
-```typescript
-router.redirect('/old-page', '/new-page', { permanent: true });
-router.redirect('/temp', '/elsewhere', { statusCode: 302 });
-```
-
-### `router.header(source, headers, options?)`
-
-Add custom headers for a path pattern.
-
-```typescript
-router.header('/api/(.*)', [
-  { key: 'X-Custom-Header', value: 'value' }
-]);
-```
-
-### `router.cacheControl(source, options)`
-
-Set cache control headers. Options include `public`, `private`, `maxAge`, `sMaxAge`, `immutable`, etc.
-
-```typescript
-router.cacheControl('/static/(.*)', {
-  public: true,
-  maxAge: '1 week',
-  immutable: true
-});
-```
-
-### `router.cleanUrls`
-
-Set whether to enable clean URLs (removes file extensions).
-
-```typescript
-router.cleanUrls = true;
-```
-
-### `router.trailingSlash`
-
-Set whether to normalize paths to include trailing slashes.
-
-```typescript
-router.trailingSlash = true;
-```
-
-### `router.bulkRedirectsPath`
-
-Set the path to a bulk redirects JSON file.
-
-```typescript
-router.bulkRedirectsPath = './bulkRedirectsDemo.json';
-```
-
-## Conditional Routing
-
-The SDK supports powerful conditional routing using `has` and `missing` conditions. These conditions can be added to rewrites, redirects, headers, and cache control rules.
-
-### Condition Types
-
-- `header`: Match HTTP headers
-- `cookie`: Match cookies
-- `host`: Match the request host
-- `query`: Match query parameters
-- `path`: Match the request path pattern
-
-### Simple Presence Check
-
-```typescript
-// Only rewrite if x-api-key header exists
-router.rewrite('/api/(.*)', 'https://backend.com/$1', {
-  has: [
-    { type: 'header', key: 'x-api-key' }
-  ]
-});
-
-// Redirect if auth-token cookie is missing
-router.redirect('/dashboard', '/login', {
-  missing: [
-    { type: 'cookie', key: 'auth-token' }
-  ]
-});
-```
-
-### Conditional Operators
-
-The SDK supports advanced matching operators for more complex conditions:
-
-#### Equality Operators
-
-```typescript
-// Exact match using 'eq'
-router.rewrite('/api/(.*)', 'https://backend.com/$1', {
-  has: [
-    { type: 'header', key: 'x-api-version', eq: 'v2' }
-  ]
-});
-
-// Not equal using 'neq'
-router.redirect('/beta/(.*)', '/stable/$1', {
-  has: [
-    { type: 'cookie', key: 'beta-access', neq: 'granted' }
-  ]
-});
-```
-
-#### Inclusion Operators
-
-```typescript
-// Must be one of (inclusion)
-router.rewrite('/admin/(.*)', 'https://admin.backend.com/$1', {
-  has: [
-    { type: 'header', key: 'x-user-role', inc: ['admin', 'moderator', 'superuser'] }
-  ]
-});
-
-// Must NOT be one of (non-inclusion)
-router.redirect('/public/(.*)', '/private/$1', {
-  has: [
-    { type: 'header', key: 'x-user-role', ninc: ['guest', 'anonymous'] }
-  ]
-});
-```
-
-#### String Pattern Operators
+export const config: VercelConfig = {
+  buildCommand: 'npm run build',
+  framework: 'nextjs',
+  
+  rewrites: [
+    // Simple rewrite
+    router.rewrite('/api/(.*)', 'https://backend.api.example.com/$1'),
+    
+    // Rewrite with transforms
+    router.rewrite('/users/:userId', 'https://api.example.com/users/$1', 
+      ({ userId, env }) => ({
+        requestHeaders: {
+          'x-user-id': userId,
+          'authorization': `Bearer ${env.API_TOKEN}`
+        }
+      })
+    )
+  ],
+  
+  redirects: [
+    router.redirect('/old-docs', '/docs', { permanent: true })
+  ],
 
-```typescript
-// Starts with (prefix)
-router.rewrite('/staging/(.*)', 'https://staging.backend.com/$1', {
-  has: [
-    { type: 'cookie', key: 'session', pre: 'staging-' }
-  ]
-});
+  headers: [
+    router.cacheControl('/static/(.*)', {
+      public: true,
+      maxAge: '1 week',
+      immutable: true
+    })
+  ],
 
-// Ends with (suffix)
-router.redirect('/dev/(.*)', '/development/$1', {
-  has: [
-    { type: 'header', key: 'x-environment', suf: '-dev' }
+  crons: [
+    { path: '/api/cleanup', schedule: '0 0 * * *' }
   ]
-});
+};
 ```
 
-#### Numeric Comparison Operators
-
-```typescript
-// Greater than
-router.rewrite('/api/v3/(.*)', 'https://api-v3.backend.com/$1', {
-  has: [
-    { type: 'query', key: 'version', gt: 2 }
-  ]
-});
-
-// Greater than or equal
-router.rewrite('/premium/(.*)', '/premium-content/$1', {
-  has: [
-    { type: 'header', key: 'x-subscription-tier', gte: 3 }
-  ]
-});
+## Features
 
-// Less than
-router.redirect('/legacy/(.*)', '/upgrade/$1', {
-  has: [
-    { type: 'query', key: 'api-version', lt: 2 }
-  ]
-});
+- **Type-safe configuration** - Full TypeScript support with IDE autocomplete
+- **Readable syntax** - Helper methods like `router.redirect()`, `router.rewrite()`, `router.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
 
-// Less than or equal
-router.rewrite('/free/(.*)', '/free-tier/$1', {
-  has: [
-    { type: 'header', key: 'x-plan', lte: 1 }
-  ]
-});
-```
-
-### Host and Path Matching
+## Build-Time Compilation
 
-```typescript
-// Host matching (no key required)
-router.redirect('/(.*)', 'https://www.example.com/$1', {
-  has: [
-    { type: 'host', value: 'example.com' }
-  ]
-});
-
-// Path pattern matching (no key required)
-router.rewrite('/(.*)', '/internal/$1', {
-  has: [
-    { type: 'path', value: '^/api/v[0-9]+/.*' }
-  ]
-});
+Your `vercel.ts` is automatically compiled to `vercel.json` during:
+```bash
+vercel build
+vercel dev
+vercel deploy
 ```
 
-### Multiple Conditions
+No manual build step needed - the Vercel CLI handles compilation automatically.
 
-All conditions in a `has` or `missing` array must match (AND logic):
+## CLI Commands
 
-```typescript
-router.rewrite('/secure/(.*)', 'https://secure.backend.com/$1', {
-  has: [
-    { type: 'header', key: 'x-api-key' },
-    { type: 'header', key: 'x-user-role', inc: ['admin', 'superuser'] },
-    { type: 'cookie', key: 'session', pre: 'secure-' },
-    { type: 'query', key: 'version', gte: 2 }
-  ]
-});
-```
+For development and validation:
 
-### Combining with Transforms
+```bash
+# Compile vercel.ts to JSON (output to stdout)
+npx @vercel/config compile
 
-You can combine conditions with transforms for powerful routing logic:
+# Validate config for errors and show summary
+npx @vercel/config validate
 
-```typescript
-router.rewrite('/api/users/:userId', 'https://backend.com/users/$1', ({ userId, env }) => ({
-  has: [
-    { type: 'header', key: 'authorization', pre: 'Bearer ' },
-    { type: 'header', key: 'x-api-version', gte: 2 }
-  ],
-  missing: [
-    { type: 'header', key: 'x-deprecated-header' }
-  ],
-  requestHeaders: {
-    'x-user-id': userId,
-    'x-internal-key': env.INTERNAL_API_KEY
-  }
-}));
+# Generate vercel.json locally (for development)
+npx @vercel/config generate
 ```
 
-### Available Operators
-
-| Operator | Type | Description | Example |
-|----------|------|-------------|---------|
-| `eq` | string \| number | Exact equality match | `{ eq: 'v2' }` |
-| `neq` | string | Not equal | `{ neq: 'guest' }` |
-| `inc` | string[] | Value is one of | `{ inc: ['admin', 'mod'] }` |
-| `ninc` | string[] | Value is not one of | `{ ninc: ['guest', 'banned'] }` |
-| `pre` | string | Starts with prefix | `{ pre: 'Bearer ' }` |
-| `suf` | string | Ends with suffix | `{ suf: '-dev' }` |
-| `gt` | number | Greater than | `{ gt: 2 }` |
-| `gte` | number | Greater than or equal | `{ gte: 3 }` |
-| `lt` | number | Less than | `{ lt: 5 }` |
-| `lte` | number | Less than or equal | `{ lte: 10 }` |
-
 ## Important Notes
 
-- **One config file only**: You cannot have both `vercel.ts` and `vercel.json`. The build will fail if both exist.
-- **Automatic gitignore**: The generated `.vercel/vercel.json` file is automatically ignored by git (in the `.vercel/` directory).
-- **No manual compilation needed**: The Vercel CLI handles compilation automatically - no need to run a separate command.
+- **One config file only**: You cannot have both `vercel.ts` and `vercel.json`.
+- **Transforms compile to routes**: When you add transforms to rewrites/redirects (like `requestHeaders`), they're compiled to the lower-level `routes` primitive internally.
+- **Automatic compilation**: The Vercel CLI compiles `vercel.ts` automatically.
 
 ## Learn More
 

package/dist/cli.js

@@ -27,6 +27,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = require("fs");
 const path_1 = require("path");
 const fs_2 = require("fs");
+const validation_1 = require("./utils/validation");
 /**
  * Named exports that should NOT be auto-converted to config
  * (these are route-based features that compile into the routes array, or internal module properties)
@@ -68,46 +69,51 @@ async function configureRouter() {
     };
 }
 /**
- * Read existing vercel.json and extract fields to preserve
+ * Compile vercel.ts to JSON and output to stdout
  */
-function readExistingVercelConfig() {
-    const vercelJsonPath = (0, path_1.resolve)(process.cwd(), "vercel.json");
-    if (!(0, fs_2.existsSync)(vercelJsonPath)) {
-        return {};
+async function compileConfig() {
+    try {
+        const config = await configureRouter();
+        const json = JSON.stringify(config, null, 2);
+        console.log(json);
+    }
+    catch (error) {
+        console.error("Failed to compile config:", error);
+        process.exit(1);
     }
+}
+/**
+ * Validate the vercel.ts config
+ */
+async function validateConfig() {
+    var _a, _b, _c, _d;
     try {
-        const content = (0, fs_1.readFileSync)(vercelJsonPath, "utf-8");
-        const existing = JSON.parse(content);
-        // Extract fields we want to preserve
-        const preserved = {};
-        if (existing.buildCommand) {
-            preserved.buildCommand = existing.buildCommand;
-        }
-        if (existing.installCommand) {
-            preserved.installCommand = existing.installCommand;
-        }
-        return preserved;
+        const config = await configureRouter();
+        // Validate static fields
+        (0, validation_1.validateStaticFields)(config);
+        console.log("✓ Config is valid");
+        console.log(`  - buildCommand: ${config.buildCommand || '(not set)'}`);
+        console.log(`  - framework: ${config.framework || '(not set)'}`);
+        console.log(`  - routes: ${((_a = config.routes) === null || _a === void 0 ? void 0 : _a.length) || 0} route(s)`);
+        console.log(`  - redirects: ${((_b = config.redirects) === null || _b === void 0 ? void 0 : _b.length) || 0} redirect(s)`);
+        console.log(`  - rewrites: ${((_c = config.rewrites) === null || _c === void 0 ? void 0 : _c.length) || 0} rewrite(s)`);
+        console.log(`  - headers: ${((_d = config.headers) === null || _d === void 0 ? void 0 : _d.length) || 0} header(s)`);
     }
     catch (error) {
-        console.warn("Could not read existing vercel.json:", error);
-        return {};
+        console.error("✗ Config validation failed:");
+        console.error(`  ${error}`);
+        process.exit(1);
     }
 }
 /**
- * Generates the vercel.json file
+ * Generate vercel.json file (for backwards compatibility / development)
  */
 async function generateVercelConfig() {
     try {
         const config = await configureRouter();
-        const existingFields = readExistingVercelConfig();
-        // Merge: generated config takes precedence, but preserve existing build/install commands if not set
-        const mergedConfig = {
-            ...existingFields,
-            ...config,
-        };
-        const vercelConfig = JSON.stringify(mergedConfig, null, 2);
+        const json = JSON.stringify(config, null, 2);
         const outputPath = (0, path_1.resolve)(process.cwd(), "vercel.json");
-        (0, fs_1.writeFileSync)(outputPath, vercelConfig);
+        (0, fs_1.writeFileSync)(outputPath, json);
         console.log("Successfully generated vercel.json");
     }
     catch (error) {
@@ -115,7 +121,30 @@ async function generateVercelConfig() {
         process.exit(1);
     }
 }
+/**
+ * CLI entry point
+ */
+async function main() {
+    const command = process.argv[2];
+    switch (command) {
+        case 'compile':
+            await compileConfig();
+            break;
+        case 'validate':
+            await validateConfig();
+            break;
+        case 'generate':
+        case undefined:
+            // Default to generate for backwards compatibility
+            await generateVercelConfig();
+            break;
+        default:
+            console.error(`Unknown command: ${command}`);
+            console.error('Available commands: compile, validate, generate');
+            process.exit(1);
+    }
+}
 // Run if this file is executed directly
 if (require.main === module) {
-    generateVercelConfig();
+    main();
 }