/astro-auto-adapter

Choose Astro Adapters based off of the `ASTRO_ADAPTER_MODE` environment variable

Primary LanguageTypeScriptMIT LicenseMIT

astro-auto-adapter

Open Bundle

NPM | GitHub | Licence

Let's you choose Astro Adapters based off of the ASTRO_ADAPTER_MODE environment variable.

Supported Adapters:

What's New? 🚀

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. Now, we've added some magic to automatically detect the deployment environment you're using.

For example, if you're deploying on Vercel Serverless, the VERCEL environment variable is set to 1, and we'll automatically choose the Vercel serverless adapter for you. Neat, right?

Dive into the docs to see the magic behind each adapter platform:

Heads Up: Some adapters require additional configuration. Don't worry; we've got detailed examples below to guide you through it.

Installation

npm install astro-auto-adapter
Others 
yarn add astro-auto-adapter

or

pnpm install astro-auto-adapter

Usage

adapter Function

First, import the necessary types and the adapter function from the package:

import { adapter, type IAdapterOptions } from "astro-auto-adapter";

Next, call the adapter() function with the desired adapter type and options:

const astroAdapter = await adapter("netlify", {
  netlify: {
    dist: new URL("path/to/dist", import.meta.url),
  },
});

Adapter Options

Here is an overview of the available adapter options:

VercelAdapterOptions

Configuration options for the Vercel serverless adapter.

import type { VercelAdapterOptions } from "astro-auto-adapter";
VercelStaticAdapterOptions

Configuration options for the Vercel static adapter.

import type { VercelStaticAdapterOptions } from "astro-auto-adapter";
NodeAdapterOptions

Configuration options for the Node adapter.

import type { NodeAdapterOptions } from "astro-auto-adapter";
CloudflareAdapterOptions

Configuration options for the Cloudflare adapter.

import type { CloudflareAdapterOptions } from "astro-auto-adapter";
DenoAdapterOptions

Configuration options for the Deno adapter.

import type { DenoAdapterOptions } from "astro-auto-adapter";
NetlifyAdapterOptions

Configuration options for the Netlify adapter.

import type { NetlifyAdapterOptions } from "astro-auto-adapter";

Environment Variable

You 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 defaults to the "node" adapter.

export ASTRO_ADAPTER_MODE="netlify"

Default Export

The package also includes a default export that can be used as a shorthand for calling the adapter() function.

import adapter from "astro-auto-adapter";

const astroAdapter = await adapter("netlify", {
  netlify: {
    dist: new URL("path/to/dist", import.meta.url),
  },
});

Examples

Here are some examples of how to use the package with various adapter types and configurations:

Cloudflare

import { adapter } from "astro-auto-adapter";

/** @type {import('astro-auto-adapter').CloudflareAdapterOptions} */
const options = {
  mode: "directory",
};

const astroAdapter = await adapter("cloudflare", { cloudflare: options });

Deno

import { adapter } from "astro-auto-adapter";

/** @type {import('astro-auto-adapter').DenoAdapterOptions} */
const options = {
  port: 3000,
  hostname: "localhost",
};

const astroAdapter = await adapter("deno", { deno: options });

Netlify

import { adapter } from "astro-auto-adapter";

/** @type {import('astro-auto-adapter').NetlifyFunctionsAdapterOptions} */
const options = {
  dist: new URL("path/to/dist", import.meta.url),
  builders: true,
  binaryMediaTypes: ["application/octet-stream"],
};

const astroAdapter = await adapter("netlify", { netlify: options });

Netlify Static

import { adapter } from "astro-auto-adapter";

/** @type {import('astro-auto-adapter').NetlifyStaticAdapterOptions} */
const options = {
  dist: new URL("path/to/dist", import.meta.url),
};

const astroAdapter = await adapter("netlify-static", { "netlify-static": options });

Vercel

import { adapter } from "astro-auto-adapter";

/** @type {import('astro-auto-adapter').VercelAdapterOptions} */
const options = {
  // Configuration options go here
};

const astroAdapter = await adapter("vercel", { vercel: options });

Vercel Static

import { adapter } from "astro-auto-adapter";

/** @type {import('astro-auto-adapter').VercelStaticAdapterOptions} */
const options = {
  // Configuration options go here
};

const astroAdapter = await adapter("vercel-static", { "vercel-static": options });

Node

import { adapter } from "astro-auto-adapter";

/** @type {import('astro-auto-adapter').NodeAdapterOptions} */
const options = {
  // Configuration options go here
};

const astroAdapter = await adapter("node", { node: options });

output Function

The output function in astro-auto-adapter is a smart utility designed to automatically select the appropriate Astro output mode 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.

Key Features:

  • Automatic Mode Selection: Chooses the correct Astro output mode (static, server, or hybrid) based on the environment.
  • Environment Variable Support: Uses ASTRO_OUTPUT_MODE to determine the preferred mode if set.
  • Fallback to Default Mode: If the environment variable isn't set, the function falls back to a specified default mode.

Usage in Astro Projects:

To 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:

import { output } from 'astro-auto-adapter';

// Usage
const astroOutputMode = output('deno', 'hybrid');

Parameters:

  • type (optional): Type of adapter you're using (e.g., 'vercel', 'netlify'). Defaults to the value from the ASTRO_ADAPTER_MODE environment variable.
  • mode (optional): Sets Astro output mode ('static', 'server', 'hybrid'). Defaults to 'hybrid', if the ASTRO_OUTPUT_MODE environment variable isn't set.

Examples:

1. Using with Vercel:

// Automatically choose output mode for Vercel deployment, by default "hybrid"
const outputMode = output('vercel');

2. Using with Netlify:

// Use the server output for netlify
const outputMode = output('netlify', 'server');

3. Default Usage (No Specific Adapter):

// Use the default output mode "hybrid" or the one defined in `ASTRO_OUTPUT_MODE`
const outputMode = output();

Supported Adapters:

  • Vercel (static and serverless)
  • Netlify (including Netlify Edge)
  • Cloudflare
  • Deno
  • Node.js

Note: Ensure that the necessary environment variables are set appropriately for the output function to work correctly.

Showcase

A couple sites/projects that use astro-auto-adapter:

  • Your site/project here...

Contributing

I encourage you to use pnpm to contribute to this repo, but you can also use yarn or npm if you prefer.

Install all necessary packages

npm install

Then run tests

npm test

Build project

npm run build

Note: This project uses Conventional Commits standard for commits, so, please format your commits using the rules it sets out.

Licence

See the LICENSE file for license rights and limitations (MIT).