Installation

Installing Astro Maintenance

Adding the maintenance page integration to your Astro project is straightforward. Follow these steps to get started quickly.

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({
      // Maintenance mode is enabled by default
      template: "simple", // Options: 'simple', 'countdown', 'construction' or path to custom template
      title: "Site Under Maintenance",
      description:
        "We are performing scheduled maintenance. Please check back soon.",
      // Other optional parameters...
    }),
  ],
});

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.

---

💡 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 the integration, you can:

• Explore the Configuration Options to customize your maintenance page
• Learn about the different Templates available