Configuration Options

The Astro Maintenance integration is highly customizable with many options to tailor the maintenance page to your needs. This guide covers all available configuration parameters.

Basic Configuration Structure

When adding the integration to your Astro config file, you can specify various options:

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

export default defineConfig({
  integrations: [
    maintenance({
      // Your configuration options go here
      enabled: true,
      template: "simple",
      title: "Custom Maintenance Title",
      // ...other options
    }),
  ],
});

Available Options

Here’s a complete reference of all the configuration options available:

Property	Type	Description	Required
`enabled`	`boolean`	Enable or disable maintenance mode (default: `true`)	-
`template`	`'simple' \| 'countdown' \| 'construction' \| string`	Built-in template, path to custom template, or route path	-
`title`	`string`	Page title (default: `'Site under maintenance'`)	-
`description`	`string`	Description text	-
`logo`	`string`	URL to your logo image. Must reside in the `assets` or `logo` subfolder of the public folder	-
`emailAddress`	`string`	Contact email address	-
`emailText`	`string`	Text to display before the email address (default: `'Contact us:'`)	-
`copyright`	`string`	Copyright text	-
`countdown`	`string`	ISO date string for countdown timer in UTC (e.g., `'2025-12-31T23:59:59'`)	-
`override`	`string`	Query parameter to bypass maintenance mode (e.g., `'preview'`)	-
`allowedPaths`	`string[]`	Paths that bypass maintenance mode	-
`cookieName`	`string`	Override cookie name	-
`cookieMaxAge`	`number`	Cookie expiration in seconds	-
`socials`	`object`	Social media links configuration for display on maintenance pages	-

Options In Detail

`enabled`

Controls whether maintenance mode is active. Set to true to activate maintenance mode and display the maintenance page, or false to show your regular site.

maintenance({
  enabled: true, // Maintenance mode is active
});

This is useful for toggling maintenance mode without removing the integration.

`template`

Specifies which template to use for the maintenance page. You have several options:

Built-in templates: 'simple', 'countdown', or 'construction'
Path to a custom Handlebars template (e.g., './templates/custom.hbs')
Route path in your Astro site (e.g., '/custom-maintenance')

maintenance({
  template: "countdown", // Use the built-in countdown template
});

`title` and `description`

These options control the main heading and description text on the maintenance page:

maintenance({
  title: "We'll be back soon!",
  description: "Our website is currently undergoing scheduled maintenance.",
});

`logo`

URL to your company or website logo:

maintenance({
  logo: "/logo.png", // Must be in your public folder
});

The logo should be placed in your project’s public folder.

Contact Information (`emailAddress` and `emailText`)

Add contact information for visitors during maintenance:

maintenance({
  emailAddress: "[email protected]",
  emailText: "Need assistance? Contact us at:",
});

`copyright`

Add copyright information to the footer:

maintenance({
  copyright: "© 2025 Your Company",
});

`countdown`

For the countdown template, specify when maintenance will end using an ISO date string in UTC timezone:

maintenance({
  countdown: "2025-06-01T12:00:00Z", // Note the 'Z' for UTC timezone
});

When the countdown reaches zero, maintenance mode will automatically disable itself and visitors will see your actual site.

`allowedPaths`

Specify paths that should bypass maintenance mode entirely. This is useful for allowing access to specific pages or API endpoints during maintenance:

maintenance({
  enabled: true,
  allowedPaths: [
    '/api/health',     // Health check endpoint
    '/status',         // Status page
    '/admin',          // Admin area
    '/api/webhooks/*', // Wildcard support
  ],
});

Visitors accessing these paths will see your normal site content instead of the maintenance page, even when maintenance mode is enabled.

`cookieName` and `cookieMaxAge`

Control the override cookie settings:

maintenance({
  override: "preview",
  cookieName: "my_maintenance_bypass",     // Default: "astro_maintenance_override"
  cookieMaxAge: 86400,                     // 24 hours (default: 604800 - 7 days)
});

The cookie is set when users access the site with the override parameter and allows them to continue browsing without needing to use the parameter again.

`socials`

Add social media links to your maintenance page with the socials option. This displays a set of social icons with links to your profiles:

maintenance({
  socials: {
    x: "https://x.com/yourusername",
    github: "https://github.com/yourusername",
    linkedin: "https://linkedin.com/in/yourusername",
    instagram: "https://instagram.com/yourusername",
    facebook: "https://facebook.com/yourusername",
    youtube: "https://youtube.com/c/yourusername",
    mastodon: "https://mastodon.social/@yourusername",
    pinterest: "https://pinterest.com/yourusername",
    tiktok: "https://tiktok.com/@yourusername",
    discord: "https://discord.com/users/yourusername",
    slack: "https://slack.com/yourusername",
    twitch: "https://twitch.tv/yourusername",
    reddit: "https://reddit.com/user/yourusername",
  },
});

All social properties are optional - only the ones you specify will be displayed. The following social platforms are supported:

twitter - Twitter/X profile
github - GitHub profile or repository
linkedin - LinkedIn profile or company page
instagram - Instagram profile
facebook - Facebook profile or page
youtube - YouTube channel
mastodon - Mastodon profile
pinterest - Pinterest profile
tiktok - TikTok profile
discord - Discord profile
slack - Slack profile
twitch - Twitch profile
reddit - Reddit profile

All templates automatically display social links in a visually appealing way and support dark mode for better user experience.

`override`

This parameter lets you specify a query parameter to bypass the maintenance page:

maintenance({
  override: "preview", // Access the site using ?preview in the URL
});

Visitors can access the actual site by adding the parameter to the URL: https://example.com/?preview

`cookieName` and `cookieMaxAge`

These options control the cookie that’s set when using the override parameter:

maintenance({
  cookieName: "my_maintenance_override", // Default: "astro_maintenance_override"
  cookieMaxAge: 3600, // Cookie expiration in seconds (default: 604800 - 7 days)
});

Environment Variables

All configuration options can also be set using environment variables. This is useful for changing settings in different environments (development, staging, production) without rebuilding your application.

Environment variables take precedence over programmatically defined settings, allowing you to easily modify behavior in containerized deployments or CI/CD pipelines.

Environment Variable	Type	Description
`MAINTENANCE_ENABLED`	`boolean`	Enable or disable maintenance mode
`MAINTENANCE_TEMPLATE`	`string`	Template to use
`MAINTENANCE_TITLE`	`string`	Page title
`MAINTENANCE_DESCRIPTION`	`string`	Description text
`MAINTENANCE_LOGO`	`string`	URL to your logo image
`MAINTENANCE_EMAIL_ADDRESS`	`string`	Contact email address
`MAINTENANCE_EMAIL_TEXT`	`string`	Text to display before the email address
`MAINTENANCE_COPYRIGHT`	`string`	Copyright text
`MAINTENANCE_COUNTDOWN`	`string`	ISO date string for countdown timer
`MAINTENANCE_OVERRIDE`	`string`	Query parameter to bypass maintenance mode
`MAINTENANCE_ALLOWED_PATHS`	`string`	Comma-separated list of paths to bypass maintenance
`MAINTENANCE_COOKIE_NAME`	`string`	Override cookie name
`MAINTENANCE_COOKIE_MAX_AGE`	`number`	Max age of the override cookie in seconds
`MAINTENANCE_SOCIALS`	`object`	Social media links (JSON string in env variable)

Example with Environment Variables

# Enable maintenance mode with a countdown
MAINTENANCE_ENABLED=true
MAINTENANCE_TEMPLATE="countdown"
MAINTENANCE_TITLE="We're launching soon!"
MAINTENANCE_COUNTDOWN="2025-12-31T23:59:59"
MAINTENANCE_ALLOWED_PATHS="/api/health,/status,/admin"
MAINTENANCE_OVERRIDE="secure-preview-key"

This approach is particularly useful for:

Toggling maintenance mode in production without code changes
Setting different configurations across environments
Deploying containerized applications where rebuilding is costly
Managing feature flags in CI/CD pipelines

This is useful for previewing your actual site during maintenance or for letting specific users (like team members) bypass the maintenance 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

Notes About Countdown Timer

When using the countdown template, keep in mind:

The countdown displays time in UTC timezone
After the countdown ends, maintenance mode automatically disables
If there’s a time mismatch, the page will attempt to reload every 10 seconds
Format the date as an ISO string with the ‘Z’ suffix to ensure UTC timezone

Next Steps

Now that you understand all configuration options, check out our templates:

Configuration Options

Basic Configuration Structure

Available Options

Options In Detail

enabled

template

title and description

logo

Contact Information (emailAddress and emailText)

copyright

countdown

allowedPaths

cookieName and cookieMaxAge

socials

override

cookieName and cookieMaxAge

Environment Variables

Example with Environment Variables

Generating a Secure Override Key

Notes About Countdown Timer

Next Steps

`enabled`

`template`

`title` and `description`

`logo`

Contact Information (`emailAddress` and `emailText`)

`copyright`

`countdown`

`allowedPaths`

`cookieName` and `cookieMaxAge`

`socials`

`override`

`cookieName` and `cookieMaxAge`