Installation

Installing Astro Maintenance v2.0

Version 2.0 brings universal platform support for Node.js, Cloudflare Workers, Vercel, and Netlify! Adding the maintenance page integration to your Astro project is straightforward. Follow these steps to get started quickly.

Universal Platform Support

New in v2.0: Enhanced template engine that works identically across all deployment platforms:

• Node.js - Standalone and middleware modes
• Cloudflare Workers - V8 isolates with full edge computing support
• Vercel - Serverless functions and Edge Runtime
• Netlify - CDN-compatible with proper redirects

Live Platform Demos

Experience v2.0 in action:

• Vercel: astro-maintenance.vercel.app
• Netlify: astro-maintenance.netlify.app
• Cloudflare: astro-maintenance.alexander-sedeke.workers.dev

Installation

Astro includes an astro add command to automate the setup of official integrations. If you prefer, you can install integrations manually instead.

To install astro-maintenance, run the following from your project directory and follow the prompts:

# npm
npm astro add astro-maintenance

# pnpm
pnpm astro add astro-maintenance

# yarn
yarn astro add astro-maintenance

If you run into any issues, feel free to report them to us on GitHub and try the manual installation steps below.

Manual Install

First, install the astro-maintenance package:

# npm
npm install astro-maintenance

# pnpm
pnpm add astro-maintenance

# yarn
yarn add astro-maintenance

Then, apply the integration to your astro.config.* file using the integrations property:

astro.config.mjs

import { defineConfig } from 'astro/config';
import maintenance from 'astro-maintenance';

export default defineConfig({
  // ...
  integrations: [
    maintenance({
      // your configuration options
      enabled: true,
    }),
  ],
});

Basic Setup

Once installed, you need to add the integration to your Astro configuration file:

astro.config.mjs

import { defineConfig } from "astro/config";
import maintenance from "astro-maintenance";

export default defineConfig({
  integrations: [
    maintenance({
      enabled: true, // Maintenance mode enabled
      template: "simple", // Options: 'simple', 'countdown', 'construction' or imported template content
      title: "Site Under Maintenance",
      description: "We are performing scheduled maintenance. Please check back soon.",
      override: "preview", // Access site with ?preview
      // Other optional parameters...
    }),
  ],
});

Breaking Changes in v2.0

Custom templates now require ?raw imports for serverless compatibility:

❌ v1.x (deprecated):

maintenance({
  template: "./src/templates/custom.hbs", // No longer supported
});

v2.0 (required):

// Import template content using ?raw
import customTemplate from "./src/templates/custom.hbs?raw";

maintenance({
  template: customTemplate, // Pass imported content
});

Note: All built-in templates ('simple', 'countdown', 'construction') work without changes.

Verifying the Installation

After configuring the integration, you can verify that it’s working by:

1. Setting enabled: true in your configuration
2. Starting your development server or building your site
3. Visiting your site - you should see the maintenance page

Temporarily Bypassing Maintenance Mode

If you need to view your site while maintenance mode is active, you can use the override parameter:

maintenance({
  // ... other options
  override: "preview" // Add this option
})

Then access your site by adding ?preview to the URL, for example: http://localhost:3000/?preview

Using Environment Variables

You can also configure Astro Maintenance using environment variables, which is especially useful for deployment environments where you want to toggle maintenance mode without changing code or rebuilding your application.

Environment variables always take precedence over programmatically defined options. Simply prefix any option with MAINTENANCE_ (in uppercase) to set it via environment variable:

# .env file or environment variables
MAINTENANCE_ENABLED=true
MAINTENANCE_TITLE="We're performing maintenance"
MAINTENANCE_TEMPLATE="countdown"
MAINTENANCE_COUNTDOWN="2025-12-31T23:59:59"

This makes it easy to:

• Toggle maintenance mode in production without code changes
• Set different configurations for different environments
• Control maintenance mode in CI/CD pipelines

For a complete list of supported environment variables, see the Configuration Options page.

Platform-Specific Notes

Cloudflare Workers

• ✅ Full compatibility with v2.0’s enhanced template engine
• ✅ No dynamic code evaluation restrictions
• ✅ Edge computing optimized

Vercel

• ✅ Works with both Serverless Functions and Edge Runtime
• ✅ Optimized template compilation caching
• ✅ Environment variables fully supported

Netlify

• ✅ CDN-compatible with proper redirects
• ✅ Function-based middleware support
• ✅ Build-time optimizations

---

Security Tip For security reasons, avoid using a simple or guessable override key like "preview". Instead, use a long, randomly generated, URI-safe string (e.g., "bypass-43uhksdf82jd82") to reduce the risk of unintended access.

---

Generating a Secure Override Key

You can use this command in your terminal to generate a safe random key:

node -e "console.log('bypass-' + require('crypto').randomBytes(12).toString('base64url'))"

Example output:

bypass-jK8dL2t3Y_mkNCxQ9r4Ctg

Use this value as your override parameter:

maintenance({
  // ... other options
  override: "bypass-jK8dL2t3Y_mkNCxQ9r4Ctg"
})

Now you can access your site like this:

http://localhost:3000/?bypass-jK8dL2t3Y_mkNCxQ9r4Ctg

Next Steps

Now that you’ve installed Astro Maintenance v2.0, you can:

• Explore the Configuration Options to customize your maintenance page
• Learn about the different Templates available
• Check out the enhanced Custom Templates with v2.0 syntax
• View the Migration Guide for upgrading from v1.x