{"id":15673779,"url":"https://github.com/okikio/astro-auto-adapter","last_synced_at":"2026-04-06T22:02:38.703Z","repository":{"id":151775126,"uuid":"624660401","full_name":"okikio/astro-auto-adapter","owner":"okikio","description":"Choose Astro Adapters based off of the `ASTRO_ADAPTER_MODE` environment variable","archived":false,"fork":false,"pushed_at":"2025-04-30T15:13:34.000Z","size":751,"stargazers_count":12,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-30T22:34:18.774Z","etag":null,"topics":["adapters","astrojs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/okikio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-04-07T01:02:54.000Z","updated_at":"2025-04-30T21:50:19.000Z","dependencies_parsed_at":"2024-10-24T01:41:14.687Z","dependency_job_id":"78ed5dcd-4323-4e4e-b048-987663d60795","html_url":"https://github.com/okikio/astro-auto-adapter","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":"okikio/transferables","purl":"pkg:github/okikio/astro-auto-adapter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/okikio%2Fastro-auto-adapter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/okikio%2Fastro-auto-adapter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/okikio%2Fastro-auto-adapter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/okikio%2Fastro-auto-adapter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/okikio","download_url":"https://codeload.github.com/okikio/astro-auto-adapter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/okikio%2Fastro-auto-adapter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266962219,"owners_count":24012994,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-25T02:00:09.625Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adapters","astrojs"],"created_at":"2024-10-03T15:42:02.010Z","updated_at":"2026-04-06T22:02:38.692Z","avatar_url":"https://github.com/okikio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# astro-auto-adapter\n\n[![Open Bundle](https://bundlejs.com/badge-light.svg)](https://bundlejs.com/?q=astro-auto-adapter\u0026bundle \"Check the total bundle size of astro-auto-adapter\")\n\n[NPM](https://www.npmjs.com/package/astro-auto-adapter) \u003cspan style=\"padding-inline: 1rem\"\u003e|\u003c/span\u003e [GitHub](https://github.com/okikio/astro-auto-adapter#readme) \u003cspan style=\"padding-inline: 1rem\"\u003e|\u003c/span\u003e [Licence](./LICENSE)\n\nLet's you choose Astro Adapters based off of the `ASTRO_ADAPTER_MODE` environment variable. \n\n## Supported Adapters:\n* [node](https://docs.astro.build/en/guides/integrations-guide/node/)\n* [deno](https://docs.astro.build/en/guides/integrations-guide/deno/)\n* [cloudflare](https://docs.astro.build/en/guides/integrations-guide/cloudflare/)\n* [vercel](https://docs.astro.build/en/guides/integrations-guide/vercel/)\n* [netlify](https://docs.astro.build/en/guides/integrations-guide/netlify/)\n* [sst](https://sst.dev/docs/component/aws/astro/)\n\n\u003e **What's New? 🚀**\n\u003e \n\u003e `astro-auto-adapter` is now even smarter! Previously, you had to manually set the `ASTRO_ADAPTER_MODE` environment variable to choose the right Astro adapter for your project. \n\u003e Now, we've added some magic to automatically detect the deployment environment you're using. \n\u003e \n\u003e For example, if you're deploying on `Vercel`, the `VERCEL` environment variable is set to `1`, and we'll automatically choose the `Vercel` adapter for you. Neat, right?\n\u003e \n\u003e **Recent Updates:**\n\u003e - Added SST (Serverless Stack) adapter support for AWS deployments, with Astro 6 currently limited to static output\n\u003e - Deprecated separate static/edge adapters (now handled by main adapters)\n\u003e - Improved auto-detection for deployment environments\n\u003e \n\u003e Dive into the docs to see the magic behind each adapter platform:\n\u003e * [Vercel Docs](https://vercel.com/docs/projects/environment-variables/system-environment-variables#system-environment-variables)\n\u003e * [Netlify Docs](https://docs.netlify.com/configure-builds/environment-variables/#build-metadata)\n\u003e * [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/runtime-apis/web-standards/#navigatoruseragent)\n\u003e * [Deno Docs](https://deno.land/api@v1.36.3?s=Deno)\n\u003e * [SST Docs](https://sst.dev/docs/start/aws/astro/)\n\n\u003e **Important**: \n\u003e - Only install the adapters you actually use to avoid a large list of adapters you don't use\n\u003e - This package uses peer dependencies, so adapter versions are managed by your project\n\u003e - Future adapter updates don't require updating `astro-auto-adapter`\n\u003e - SST currently supports Astro 6 static output only; `server` mode is waiting on `astro-sst`\n\n## Installation\n\n**Interactive setup (recommended):**\n\nAfter installing `astro-auto-adapter`, use the interactive CLI to choose which\nplatforms you want to support. The wizard detects your package manager and\ninstalls the required adapter packages for you:\n\n```bash\n# First install the package\npnpm add astro-auto-adapter\n\n# Then run the setup wizard\npnpm astro-auto-adapter init\n```\n\nThe wizard will prompt you to select one or more deployment platforms and will\ninstall the required adapter packages automatically.\n\n---\n\n**Manual install:**\n\n```bash\npnpm install astro-auto-adapter\n```\n\n**Then install the specific adapters you need:**\n\n```bash\n# For Vercel\npnpm add @astrojs/vercel\n\n# For Netlify  \npnpm add @astrojs/netlify\n\n# For Cloudflare\npnpm add @astrojs/cloudflare\n\n# For Node.js\npnpm add @astrojs/node\n\n# For Deno\npnpm add @deno/astro-adapter\n\n# For SST\npnpm add astro-sst\n```\n\n\u003cdetails\u003e\n    \u003csummary\u003eOther package managers\u003c/summary\u003e\n\n```bash\n# npm\nnpm install astro-auto-adapter @astrojs/vercel\n\n# yarn\nyarn add astro-auto-adapter @astrojs/vercel\n\n# bun\nbun add astro-auto-adapter @astrojs/vercel\n\n# vlt\nvlt install astro-auto-adapter @astrojs/vercel\n\n# deno\ndeno add astro-auto-adapter @astrojs/vercel\n```\n\n\u003c/details\u003e\n\n## Usage\n\n### CLI\n\n`astro-auto-adapter` ships with an interactive command-line tool powered by\n[clack](https://clack.cc/). The CLI makes it easy to set up adapter support\nfor the first time, and to add or remove adapters as your project evolves.\n\n#### Commands\n\n| Command | Alias | Description |\n|---------|-------|-------------|\n| `init` | _(default)_ | Interactive setup wizard – choose platforms \u0026 install adapters |\n| `add [adapter…]` | | Add one or more adapter packages |\n| `remove [adapter…]` | `rm` | Remove adapter packages |\n| `list` | `ls` | Show all adapters and their installation status |\n\n#### Global flags\n\n| Flag | Description |\n|------|-------------|\n| `-h, --help` | Print help and exit |\n| `-v, --version` | Print the version and exit |\n\n#### First-time setup\n\n```bash\npnpm astro-auto-adapter init\n```\n\nThis will show a multiselect prompt where you choose which deployment platforms\nto support, then install the required packages using your package manager.\n\n#### Add an adapter\n\n```bash\n# Interactive — shows a prompt\npnpm astro-auto-adapter add\n\n# Direct — installs without a prompt\npnpm astro-auto-adapter add vercel\npnpm astro-auto-adapter add vercel netlify\n```\n\n#### Remove an adapter\n\n```bash\n# Interactive — shows a prompt with installed adapters\npnpm astro-auto-adapter remove\n\n# Direct — removes without a prompt\npnpm astro-auto-adapter remove vercel\n```\n\n#### List adapters\n\n```bash\npnpm astro-auto-adapter list\n```\n\n```\n◇  Available Adapters ──────────────────────────────────────╮\n│                                                           │\n│    Node.js         @astrojs/node            ✓ installed  │\n│    Vercel          @astrojs/vercel          ✓ installed  │\n│    Netlify         @astrojs/netlify           not installed│\n│    Cloudflare      @astrojs/cloudflare        not installed│\n│    Deno            @deno/astro-adapter        not installed│\n│    SST (AWS)       astro-sst                  not installed│\n│                                                           │\n├───────────────────────────────────────────────────────────╯\n```\n\n#### Environment variables (CLI)\n\n| Variable | Description |\n|----------|-------------|\n| `PACKAGE_MANAGER` | Override the detected package manager (`npm`, `pnpm`, `yarn`, `bun`, `vlt`, `deno`) |\n\n#### Supported package managers\n\nThe CLI auto-detects your package manager from the `npm_config_user_agent` environment variable\n(set automatically when running scripts) and from lockfile presence.\nAll managers tracked by the [vlt package manager benchmarks](https://benchmarks.vlt.sh/#/package-managers/clean) are supported:\n\n| Manager | Lockfile          | Install flag | Remove sub-command |\n|---------|-------------------|--------------|--------------------|\n| `npm`   | `package-lock.json` | `--save-dev` | `uninstall` |\n| `pnpm`  | `pnpm-lock.yaml`  | `-D`         | `remove` |\n| `yarn`  | `yarn.lock`       | `--dev`      | `remove` |\n| `bun`   | `bun.lock(b)`     | `-D`         | `remove` |\n| `vlt`   | `vlt-lock.json`   | `-D`         | `uninstall` |\n| `deno`  | `deno.lock`       | `--dev`      | `remove` |\n\nYou can override detection at any time by setting `PACKAGE_MANAGER=\u003cname\u003e` in your environment.\n\n---\n\n### `adapter` Function\n\nFirst, import the necessary types and the `adapter` function from the package:\n\n```ts\nimport { adapter, type IAdapterOptions } from \"astro-auto-adapter\";\n```\n\nNext, call the `adapter()` function with the desired adapter type and options:\n\n```ts\nconst astroAdapter = await adapter(\"netlify\", {\n  netlify: {\n    builders: true,\n  },\n});\n```\n\n#### Adapter Options\n\nHere is an overview of the available adapter options:\n\n##### `VercelAdapterOptions`\n\nConfiguration options for the Vercel adapter.\n\n```ts\nimport type { VercelAdapterOptions } from \"astro-auto-adapter\";\n```\n\n##### `NodeAdapterOptions`\n\nConfiguration options for the Node adapter.\n\n```ts\nimport type { NodeAdapterOptions } from \"astro-auto-adapter\";\n```\n\n##### `CloudflareAdapterOptions`\n\nConfiguration options for the Cloudflare adapter.\n\n```ts\nimport type { CloudflareAdapterOptions } from \"astro-auto-adapter\";\n```\n\n##### `DenoAdapterOptions`\n\nConfiguration options for the Deno adapter.\n\n```ts\nimport type { DenoAdapterOptions } from \"astro-auto-adapter\";\n```\n\n##### `NetlifyAdapterOptions`\n\nConfiguration options for the Netlify adapter.\n\n```ts\nimport type { NetlifyAdapterOptions } from \"astro-auto-adapter\";\n```\n\n##### `SSTAdapterOptions`\n\nConfiguration options for the SST (Serverless Stack) adapter.\n\nOn Astro 6, pair SST with `output(\"sst\", \"static\")` for now. `server` mode is still blocked upstream in `astro-sst`.\n\n```ts\nimport type { SSTAdapterOptions } from \"astro-auto-adapter\";\n```\n\n#### Error Handling\n\nIf you try to use an adapter that isn't installed, you'll get a helpful error message:\n\n```bash\nError: Package \"@astrojs/vercel\" is not installed. Please install it with:\npnpm add @astrojs/vercel\n```\n\n#### Environment Variable\n\nYou can use the `ASTRO_ADAPTER_MODE` environment variable to set the adapter type instead of providing it directly to the `adapter()` function. If the environment variable is not set, the function automatically detects the environment or defaults to the \"node\" adapter.\n\n```sh\nexport ASTRO_ADAPTER_MODE=\"netlify\"\n```\n\n#### Default Export\n\nThe package also includes a default export that can be used as a shorthand for calling the `adapter()` function.\n\n```ts\nimport adapter from \"astro-auto-adapter\";\n\nconst astroAdapter = await adapter(\"netlify\", {\n  netlify: {\n    builders: true,\n  },\n});\n```\n\n### Examples\n\nHere are some examples of how to use the package with various adapter types and configurations:\n\n#### Cloudflare\n\n```ts\nimport { adapter } from \"astro-auto-adapter\";\n\n/** @type {import('astro-auto-adapter').CloudflareAdapterOptions} */\nconst options = {\n  imageService: \"cloudflare\",\n  runtime: { mode: \"local\" }\n};\n\nconst astroAdapter = await adapter(\"cloudflare\", { cloudflare: options });\n```\n\n#### Deno\n\n```ts\nimport { adapter } from \"astro-auto-adapter\";\n\n/** @type {import('astro-auto-adapter').DenoAdapterOptions} */\nconst options = {\n  port: 3000,\n  hostname: \"localhost\",\n};\n\nconst astroAdapter = await adapter(\"deno\", { deno: options });\n```\n\n#### Netlify\n\n```ts\nimport { adapter } from \"astro-auto-adapter\";\n\n/** @type {import('astro-auto-adapter').NetlifyAdapterOptions} */\nconst options = {\n  builders: true,\n  edgeMiddleware: true,\n  binaryMediaTypes: [\"application/octet-stream\"],\n};\n\nconst astroAdapter = await adapter(\"netlify\", { netlify: options });\n```\n\n#### SST (Serverless Stack)\n\n```ts\nimport { adapter } from \"astro-auto-adapter\";\n\nconst astroAdapter = await adapter(\"sst\");\n```\n\nUse `output(\"sst\", \"static\")` on Astro 6 until `astro-sst` catches up on server entrypoints.\n\n#### Vercel\n\n```ts\nimport { adapter } from \"astro-auto-adapter\";\n\n/** @type {import('astro-auto-adapter').VercelAdapterOptions} */\nconst options = {\n  webAnalytics: { enabled: true },\n  speedInsights: { enabled: true },\n};\n\nconst astroAdapter = await adapter(\"vercel\", { vercel: options });\n```\n\n#### Node\n\n```ts\nimport { adapter } from \"astro-auto-adapter\";\n\n/** @type {import('astro-auto-adapter').NodeAdapterOptions} */\nconst options = {\n  mode: \"standalone\",\n  host: \"0.0.0.0\",\n  port: 3000,\n};\n\nconst astroAdapter = await adapter(\"node\", { node: options });\n```\n\n#### Custom/Third-Party Adapters\n\nYou can register custom adapters for platforms not included by default:\n\n```ts\nimport { adapter } from \"astro-auto-adapter\";\n\nconst astroAdapter = await adapter(\"railway\", {\n  // Configuration for your custom adapter\n  railway: { \n    region: \"us-west\",\n    environmentId: \"prod\" \n  },\n  \n  // Register the custom adapter factory\n  register: {\n    railway: async (opts) =\u003e {\n      const { default: railwayAdapter } = await import(\"@railway/astro-adapter\");\n      return railwayAdapter(opts);\n    },\n    \n    // You can register multiple custom adapters\n    \"custom-platform\": (opts) =\u003e {\n      return {\n        name: \"custom-platform-adapter\",\n        hooks: {\n          \"astro:config:setup\": ({ updateConfig }) =\u003e {\n            updateConfig({ \n              output: \"server\",\n              // Your custom configuration\n            });\n          }\n        }\n      };\n    }\n  }\n});\n```\n\n#### Type-Safe Custom Adapters\n\nFor full TypeScript support with custom adapters:\n\n```ts\nimport { adapter, createTypedAdapter } from \"astro-auto-adapter\";\nimport type { AdapterFactory } from \"astro-auto-adapter\";\n\n// 1. Define your adapter options interface\ninterface RailwayOptions {\n  region: 'us-west' | 'us-east' | 'eu-west';\n  healthCheckPath?: string;\n  environmentId?: string;\n}\n\ninterface CustomPlatformOptions {\n  apiKey: string;\n  endpoint: string;\n  timeout?: number;\n}\n\n// 2. Create type-safe adapter factories\nconst railwayAdapter = createTypedAdapter\u003cRailwayOptions\u003e(async (options) =\u003e {\n  // Full type safety here! IntelliSense knows about all properties\n  const { default: railway } = await import(\"@railway/astro-adapter\");\n  return railway({\n    region: options.region, // ✅ Autocomplete: 'us-west' | 'us-east' | 'eu-west'\n    healthCheckPath: options.healthCheckPath ?? '/health', // ✅ Optional property\n    environmentId: options.environmentId\n  });\n});\n\nconst customAdapter = createTypedAdapter\u003cCustomPlatformOptions\u003e((options) =\u003e ({\n  name: \"custom-platform-adapter\",\n  hooks: {\n    \"astro:config:setup\": ({ updateConfig }) =\u003e {\n      updateConfig({\n        output: \"server\",\n        vite: {\n          define: {\n            'process.env.API_KEY': JSON.stringify(options.apiKey), // ✅ Type-safe\n            'process.env.ENDPOINT': JSON.stringify(options.endpoint)\n          }\n        }\n      });\n    }\n  }\n}));\n\n// 3. Use with full type safety!\nconst astroAdapter = await adapter(\"railway\", {\n  railway: {\n    region: \"us-west\", // ✅ IntelliSense + validation\n    healthCheckPath: \"/api/health\", // ✅ Optional property\n    // environmentId: \"missing\" // ✅ Would show autocomplete\n  },\n  register: {\n    railway: railwayAdapter,\n    'custom-platform': customAdapter\n  }\n});\n\n// TypeScript will catch errors:\n// ❌ This would show a type error:\n// railway: { region: \"invalid-region\" } // Type error!\n```\n\n#### Alternative: Direct Type Declaration\n\nYou can also use module augmentation for global type safety:\n\n```ts\n// types/astro-auto-adapter.d.ts\ndeclare module \"astro-auto-adapter\" {\n  interface IAdapterOptions {\n    railway?: {\n      region: 'us-west' | 'us-east' | 'eu-west';\n      healthCheckPath?: string;\n      environmentId?: string;\n    };\n    'custom-platform'?: {\n      apiKey: string;\n      endpoint: string;\n      timeout?: number;\n    };\n  }\n}\n\n// Now you get type safety everywhere without generics:\nconst astroAdapter = await adapter(\"railway\", {\n  railway: {\n    region: \"us-west\", // ✅ Fully typed!\n    healthCheckPath: \"/health\"\n  }\n});\n```\n\n**Benefits of Type-Safe Custom Adapters:**\n- ✅ **Full IntelliSense** - Autocomplete for all adapter options\n- ✅ **Compile-time validation** - Catch configuration errors early  \n- ✅ **Refactoring safety** - Rename properties with confidence\n- ✅ **Documentation integration** - JSDoc comments in autocomplete\n- ✅ **Zero runtime overhead** - Types are compile-time only\n\n### **Type Safety Best Practices:**\n\n#### 1. **Define Strict Option Types**\n```ts\n// ✅ Good: Use union types for strict validation\ninterface AdapterOptions {\n  region: 'us-west' | 'us-east' | 'eu-west'; // Limited to valid values\n  memory: 512 | 1024 | 2048 | 4096; // Specific memory sizes\n  ssl?: boolean; // Optional with clear intent\n}\n\n// ❌ Avoid: Too generic\ninterface AdapterOptions {\n  region: string; // Any string accepted\n  memory: number; // Any number accepted\n}\n```\n\n#### 2. **Use JSDoc for Better Developer Experience**\n```ts\ninterface RailwayOptions {\n  /** \n   * Deployment region for your Railway service\n   * @default \"us-west\"\n   */\n  region: 'us-west' | 'us-east' | 'eu-west';\n  \n  /** \n   * Custom health check endpoint path\n   * @example \"/api/health\"\n   * @default \"/health\"\n   */\n  healthCheckPath?: string;\n}\n```\n\n#### 3. **Organize Types in Separate Files**\n```ts\n// types/railway.ts\nexport interface RailwayOptions { /* ... */ }\n\n// types/digitalocean.ts  \nexport interface DigitalOceanOptions { /* ... */ }\n```\n\n#### 4. **Provide Default Values in Factories**\n```ts\nconst railwayAdapter = createTypedAdapter\u003cRailwayOptions\u003e(async (options) =\u003e {\n  // Provide sensible defaults\n  const config = {\n    region: 'us-west',\n    healthCheckPath: '/health',\n    memory: 1024,\n    ...options // User options override defaults\n  };\n  \n  const { default: railway } = await import('@railway/astro-adapter');\n  return railway(config);\n});\n```\n\n### `output` Function\n\nThe `output` function in `astro-auto-adapter` is a smart utility designed to automatically select the appropriate [Astro output mode](https://docs.astro.build/en/guides/on-demand-rendering/) based on the target deployment environment. This function is especially useful when working with different hosting platforms, as it simplifies the process of configuring the correct output mode for Astro projects.\n\n#### Key Features:\n- **Automatic Mode Selection:** Chooses the correct Astro output mode (static or server) based on the environment.\n- **Environment Variable Support:** Uses `ASTRO_OUTPUT_MODE` to determine the preferred mode if set.\n- **Fallback to Default Mode:** If the environment variable isn't set, the function falls back to \"static\" by default.\n\n#### Usage in Astro Projects:\n\nTo use the `output` function, you need to import it into your Astro project and then call it with appropriate parameters. Here's a general structure of how to use it:\n\n```ts\nimport { output } from 'astro-auto-adapter';\n\n// Usage\nconst astroOutputMode = output('deno', 'server');\n```\n\n#### Parameters:\n- `type` (optional): Type of adapter you're using (e.g., 'vercel', 'netlify', 'sst'). Defaults to the value from the `ASTRO_ADAPTER_MODE` environment variable.\n- `mode` (optional): Sets Astro output mode ('static' or 'server'). Defaults to 'static', if the `ASTRO_OUTPUT_MODE` environment variable isn't set.\n\n\u003e **Note**: As of Astro v5, `hybrid` mode has been deprecated. Both `server` and `static` modes now support selective rendering using `export const prerender = true | false;` on individual pages.\n\n#### Examples:\n\n**1. Using with Vercel:**\n\n```ts\n// Automatically choose output mode for Vercel deployment, defaults to \"static\"\nconst outputMode = output('vercel');\n```\n\n**2. Using with Netlify:**\n\n```ts\n// Use the server output for netlify\nconst outputMode = output('netlify', 'server');\n```\n\n**3. Using with SST:**\n\n```ts\n// Astro 6 currently supports SST in static mode only\nconst outputMode = output('sst', 'static');\n```\n\n**4. Hybrid Mode (Astro v4 \u0026 v5 Compatible):**\n\n```ts\n// Astro v4: Uses hybrid mode natively\n// Astro v5: Automatically converts to server mode with warning\nconst outputMode = output('vercel', 'hybrid');\n\n// Modern approach (works in both versions):\nconst outputMode = output('vercel', 'server');\n// Then use selective prerendering in individual pages:\n// export const prerender = true; // Static page\n// export const prerender = false; // Server-rendered page\n```\n\n**5. Selective Rendering (Astro v5 Preferred):**\n\n```ts\n// Use server mode with selective prerendering\nconst outputMode = output('vercel', 'server');\n\n// Then in individual pages:\n// src/pages/static-page.astro\nexport const prerender = true; // This page will be static\n\n// src/pages/dynamic-page.astro  \nexport const prerender = false; // This page will be server-rendered\n```\n\n**6. Default Usage (No Specific Adapter):**\n\n```ts\n// Use the default output mode \"static\" or the one defined in `ASTRO_OUTPUT_MODE`\nconst outputMode = output();\n```\n\n#### Supported Adapters:\n- Vercel\n- Netlify\n- Cloudflare\n- Deno\n- Node.js\n- SST (Serverless Stack, Astro 6 static output only for now)\n- Custom adapters via `register` option\n\n#### Version Compatibility:\n- **Astro v4**: Full support including `hybrid` mode\n- **Astro v5+**: Full support with automatic `hybrid` → `server` conversion\n- **Backward Compatible**: Works seamlessly across version upgrades\n\n\u003e **Note**: Ensure that the necessary environment variables are set appropriately for the `output` function to work correctly.\n\n## ⚠️ Deprecated Features\n\nThe following adapter types have been deprecated and consolidated into their main adapters:\n\n- `netlify-static` → Use `netlify` with output mode `static`\n- `netlify-edge` → Use `netlify` with appropriate configuration\n- `vercel-static` → Use `vercel` with output mode `static`  \n- `vercel-edge` → Use `vercel` with appropriate configuration\n\n**Astro Version Compatibility:**\n- `hybrid` output mode → **Astro v4**: Supported natively, **Astro v5+**: Auto-converts to `server` mode with selective prerendering\n\n**Migration Examples:**\n```ts\n// ❌ Old (deprecated)\nconst adapter = await adapter(\"vercel-static\", { \"vercel-static\": options });\n\n// ✅ New (recommended)\nconst adapter = await adapter(\"vercel\", { vercel: options });\nconst outputMode = output(\"vercel\", \"static\");\n\n// ✅ Hybrid mode compatibility (works in both v4 and v5)\nconst outputMode = output(\"vercel\", \"hybrid\"); // Auto-converts to \"server\" in v5\n\n// ✅ Modern selective rendering (Astro v5 preferred)\nconst outputMode = output(\"vercel\", \"server\");\n// Then use export const prerender = true; on static pages\n```\n\n## Showcase\n\nA couple sites/projects that use `astro-auto-adapter`:\n\n- Your site/project here...\n\n### **Real-World Type-Safe Custom Adapter Example:**\n\n```ts\n// types/adapters.ts - Define your custom adapter types\nexport interface RailwayOptions {\n  region: 'us-west' | 'us-east' | 'eu-west';\n  healthCheckPath?: string;\n  environmentId?: string;\n  memory?: 512 | 1024 | 2048 | 4096;\n}\n\nexport interface DigitalOceanOptions {\n  dropletSize: 's-1vcpu-1gb' | 's-2vcpu-2gb' | 's-4vcpu-8gb';\n  region: 'nyc1' | 'sfo3' | 'fra1';\n  enableBackups?: boolean;\n}\n```\n\n```ts\n// astro.config.mjs - Use with full type safety\nimport { defineConfig } from 'astro/config';\nimport { adapter, output, createTypedAdapter } from 'astro-auto-adapter';\nimport type { RailwayOptions, DigitalOceanOptions } from './types/adapters';\n\n// Create type-safe adapter factories\nconst railwayAdapter = createTypedAdapter\u003cRailwayOptions\u003e(async (options) =\u003e {\n  const { default: railway } = await import('@railway/astro-adapter');\n  return railway({\n    region: options.region,\n    healthCheckPath: options.healthCheckPath ?? '/health',\n    environmentId: options.environmentId,\n    memory: options.memory ?? 1024\n  });\n});\n\nconst digitalOceanAdapter = createTypedAdapter\u003cDigitalOceanOptions\u003e(async (options) =\u003e {\n  const { default: digitalOcean } = await import('@digitalocean/astro-adapter');\n  return digitalOcean({\n    dropletSize: options.dropletSize,\n    region: options.region,\n    enableBackups: options.enableBackups ?? true\n  });\n});\n\nexport default defineConfig({\n  output: output('railway', 'server'),\n  adapter: await adapter('railway', {\n    railway: {\n      region: 'us-west', // ✅ IntelliSense autocomplete!\n      healthCheckPath: '/api/health',\n      environmentId: process.env.RAILWAY_ENVIRONMENT_ID,\n      memory: 2048 // ✅ Type validation: only 512|1024|2048|4096 allowed\n    },\n    register: {\n      railway: railwayAdapter,\n      digitalocean: digitalOceanAdapter\n    }\n  })\n});\n```\n\n```ts\n// Alternative: Environment-based selection with type safety\nimport { getEnv } from \"astro-auto-adapter\";\n\nconst adapterType = getEnv(\"DEPLOYMENT_TARGET\") || 'railway';\n\nexport default defineConfig({\n  output: output(adapterType, 'server'),\n  adapter: await adapter(adapterType, {\n    railway: {\n      region: 'us-west', // ✅ Fully typed\n      memory: 1024\n    },\n    digitalocean: {\n      dropletSize: 's-2vcpu-2gb', // ✅ Autocomplete + validation\n      region: 'nyc1'\n    },\n    register: {\n      railway: railwayAdapter,\n      digitalocean: digitalOceanAdapter\n    }\n  })\n});\n```\n  \n## Contributing\n\nThis project uses [pnpm](https://pnpm.io/) as the package manager.\n\nInstall all necessary packages\n\n```bash\npnpm install\n```\n\nThen run tests\n\n```bash\npnpm test\n```\n\nBuild project\n\n```bash\npnpm run build\n```\n\n### Architecture Notes\n\nThis package uses **peer dependencies** for adapters rather than bundling them directly. This approach:\n- ✅ Reduces bundle size (users only install adapters they use)\n- ✅ Allows automatic updates to latest adapter versions  \n- ✅ Prevents version conflicts with user projects\n- ✅ Eliminates need for constant package updates\n\n\u003e **Note**: _This project uses [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard for commits, so, please format your commits using the rules it sets out._\n\n## Licence\n\nSee the [LICENSE](./LICENSE) file for license rights and limitations (MIT).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fokikio%2Fastro-auto-adapter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fokikio%2Fastro-auto-adapter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fokikio%2Fastro-auto-adapter/lists"}