Fix: Config Contains Legacy Key in Astro

What Causes This Error?

This error occurs when your Astro config contains deprecated configuration options that have been renamed or removed in newer versions. Astro evolves and sometimes changes its configuration API.

The Problem

// astro.config.mjs
export default defineConfig({
  // ❌ Legacy keys (examples from older versions)
  buildOptions: {
    site: 'https://example.com',
  },
  devOptions: {
    port: 3000,
  },
});

The Fix

Update to Current API

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  // ✅ Current configuration
  site: 'https://example.com',
  server: {
    port: 3000,
  },
});

Common Scenarios

Legacy to Current Mappings

// ❌ Old (v0.x - v1.x era)
export default defineConfig({
  buildOptions: {
    site: 'https://example.com',
    sitemap: true,
  },
  devOptions: {
    port: 3000,
    tailwindConfig: './tailwind.config.js',
  },
  markdownOptions: {
    render: ['@astrojs/markdown-remark'],
  },
});

// ✅ Current (v2.x+)
export default defineConfig({
  site: 'https://example.com',
  server: {
    port: 3000,
  },
  markdown: {
    // Markdown config
  },
  integrations: [
    sitemap(),
    tailwind({ configFile: './tailwind.config.js' }),
  ],
});

Server Configuration

// ❌ Legacy
export default defineConfig({
  devOptions: {
    port: 3000,
    host: true,
  },
});

// ✅ Current
export default defineConfig({
  server: {
    port: 3000,
    host: true,
  },
});

Build Configuration

// ❌ Legacy
export default defineConfig({
  buildOptions: {
    site: 'https://example.com',
    drafts: true,
  },
});

// ✅ Current
export default defineConfig({
  site: 'https://example.com',
  markdown: {
    drafts: true,
  },
});

Renderers to Integrations

// ❌ Old renderers system
export default defineConfig({
  renderers: [
    '@astrojs/renderer-react',
    '@astrojs/renderer-vue',
  ],
});

// ✅ Current integrations
import react from '@astrojs/react';
import vue from '@astrojs/vue';

export default defineConfig({
  integrations: [
    react(),
    vue(),
  ],
});

Markdown Configuration

// ❌ Legacy
export default defineConfig({
  markdownOptions: {
    render: ['@astrojs/markdown-remark'],
  },
});

// ✅ Current
export default defineConfig({
  markdown: {
    remarkPlugins: [],
    rehypePlugins: [],
    shikiConfig: {
      theme: 'dracula',
    },
  },
});

CSS Configuration

// ❌ Legacy
export default defineConfig({
  styleOptions: {
    postcss: true,
  },
});

// ✅ Current
export default defineConfig({
  vite: {
    css: {
      postcss: './postcss.config.js',
    },
  },
});

Experimental Features

// ❌ Some experimental features become stable with different keys
export default defineConfig({
  experimental: {
    ssr: true,  // Old
  },
});

// ✅ Now standard config
export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
});

Check Astro Version

# See your current Astro version
npm ls astro

# Check migration guides for your version
# https://docs.astro.build/en/guides/upgrade-to/v4/

Update Config for v4

// ✅ Astro v4+ configuration
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://example.com',
  output: 'static',  // or 'server' or 'hybrid'
  integrations: [
    react(),
    tailwind(),
    sitemap(),
  ],
  server: {
    port: 3000,
    host: true,
  },
  build: {
    assets: '_assets',
  },
  markdown: {
    shikiConfig: {
      theme: 'one-dark-pro',
    },
  },
});

Remove Deprecated Keys

// Common deprecated keys to remove:
export default defineConfig({
  // ❌ Remove these:
  // buildOptions
  // devOptions
  // markdownOptions
  // styleOptions
  // renderers
  // pages (use src/pages instead)
  // public (use public/ folder instead)

  // ✅ Use current API instead
});

Quick Checklist

• Check the error message for specific legacy key name
• Consult Astro migration guides
• Update buildOptions → top-level or build
• Update devOptions → server
• Update renderers → integrations
• Update markdownOptions → markdown
• Run npm ls astro to check version