Config imports API Reference

Added in: astro@5.7.0

This virtual module astro:config exposes a non-exhaustive, serializable, type-safe version of the Astro configuration. There are two submodules for accessing different subsets of your configuration values: /client and /server.

All available config values can be accessed from astro:config/server. However, for code executed on the client, only those values exposed by astro:config/client will be available. This protects your information by only making some data available to the client.

Imports from astro:config/client

The following helpers are imported from the client directory of the virtual config module.

import {
  i18n,
  trailingSlash,
  base,
  build,
  site,
  compressHTML,
} from "astro:config/client";

Use this submodule for client-side code:

src/utils.js

import { trailingSlash } from "astro:config/client";

function addForwardSlash(path) {
  if (trailingSlash === "always") {
    return path.endsWith("/") ? path : path + "/"
  } else {
    return path
  }
}

See more about the configuration imports available from astro:config/client:

• i18n
• trailingSlash
• base
• build.format
• site
• compressHTML

Imports from astro:config/server

The following helpers are imported from the server directory of the virtual config module.

import {
  i18n,
  trailingSlash,
  base,
  build,
  site,
  srcDir,
  cacheDir,
  outDir,
  publicDir,
  root,
  compressHTML,
} from "astro:config/server";

These imports include everything available from astro:config/client as well as additional sensitive information about your file system configuration that is not safe to expose to the client.

Use this submodule for server side code:

astro.config.mjs

import { integration } from "./integration.mjs";

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

integration.mjs

import { outDir } from "astro:config/server";
import { writeFileSync } from "node:fs";
import { fileURLToPath } from "node:url";

export default function() {
  return {
    name: "internal-integration",
    hooks: {
      "astro:build:done": () => {
        let file = new URL("result.json", outDir);
        // generate data from some operation
        let data = JSON.stringify([]);
        writeFileSync(fileURLToPath(file), data, "utf-8");
      }
    }
  }
}

See more about the configuration imports available from astro:config/server:

• i18n
• trailingSlash
• base
• build.format
• build.client
• build.server
• site
• srcDir
• cacheDir
• outDir
• publicDir
• root
• compressHTML

Imports from astro/config

The following helpers are imported from the regular config module:

import {
  defineConfig,
  envField,
  fontProviders,
  getViteConfig,
  mergeConfig,
  passthroughImageService,
  sessionDrivers,
  sharpImageService,
  validateConfig,
} from "astro/config";

defineConfig()

Type: (config: AstroUserConfig) => AstroUserConfig

Configures your project with type safety in a supported Astro configuration file.

envField

Type: object

Added in: astro@5.0.0

Describes the supported data types when defining environment variables.

Each data type must define the variable type with context ("client" or "server") and access ("secret" or "public"). In addition, you can define a default value, specify whether the variable is optional (default false), and some data types provide optional validation methods.

Learn more about using type safe environment variables in your Astro project.

envField.string()

Type: (options: StringFieldInput) => StringField

Defines an environment variable of string type. You can perform string validation with Zod using the following properties: max, min, length, url, includes, startsWith, and endsWith.

The following example defines the expected shape for an environment variable storing an API URL:

astro.config.mjs

import { defineConfig, envField } from "astro/config";

export default defineConfig({
  env: {
    schema: {
      API_URL: envField.string({
        context: "client",
        access: "public",
        optional: false,
        default: "",
        min: 12,
        url: true,
        includes: "astro",
        startsWith: "https",
      }),
    }
  }
})

envField.number()

Type: (options: NumberFieldInput) => NumberField

Defines an environment variable of number type. You can perform number validation with Zod using the following properties: gt, lt, min, max, and int.

The following example defines the expected shape for an environment variable storing an API port:

astro.config.mjs

import { defineConfig, envField } from "astro/config";

export default defineConfig({
  env: {
    schema: {
      API_PORT: envField.number({
        context: "server",
        access: "public",
        optional: true,
        default: 4321,
        min: 2,
        int: true,
      }),
    }
  }
})

envField.boolean()

Type: (options: BooleanFieldInput) => BooleanField

Defines an environment variable of boolean type.

The following example defines the expected shape for an environment variable storing whether analytics are enabled:

astro.config.mjs

import { defineConfig, envField } from "astro/config";

export default defineConfig({
  env: {
    schema: {
      ANALYTICS_ENABLED: envField.boolean({
        context: "client",
        access: "public",
        optional: true,
        default: true,
      }),
    }
  }
})

envField.enum()

Type: (options: EnumFieldInput<T>) => EnumField

Defines an environment variable of enum type by providing the allowed values as an array.

The following example defines the expected shape for an environment variable storing the configured debug mode:

astro.config.mjs

import { defineConfig, envField } from "astro/config";

export default defineConfig({
  env: {
    schema: {
      DEBUG_MODE: envField.enum({
        context: "server",
        access: "public",
        values: ['info', 'warnings', 'errors'], // required
        optional: true,
        default: 'errors',
      }),
    }
  }
})

fontProviders

Type: object

Added in: astro@6.0.0 Beta

Describes the built-in provider used to retrieve the configured font.

getViteConfig()

Type: (userViteConfig: ViteUserConfig, inlineAstroConfig?: AstroInlineConfig) => ViteUserConfigFn

Retrieves the Vite configuration to use by merging a custom Vite configuration object and an optional Astro configuration object. This is useful to set up Vitest for testing.

mergeConfig()

See mergeConfig() in the Programmatic API reference.

passthroughImageService()

Type: () => ImageServiceConfig

Retrieves a no-op image service. This is useful when your adapter does not support Astro’s built-in Sharp image optimization and you want to use the <Image /> and <Picture /> components.

The following example defines passthroughImageService() as image service in the Astro configuration file to avoid Sharp image processing:

astro.config.mjs

import { defineConfig, passthroughImageService } from "astro/config";

export default defineConfig({
  image: {
    service: passthroughImageService()
  }
});

Learn more about configuring a no-op passthrough service.

sessionDrivers

Type: object

Added in: astro@5.7.0

Describes the built-in driver used for session storage.

The following example configures the Redis driver to enable sessions:

astro.config.mjs

import { defineConfig, sessionDrivers } from "astro/config";

export default defineConfig({
  session: {
    driver: sessionDrivers.redis({
      url: process.env.REDIS_URL
    }),
  }
})

Learn more about using sessions in your Astro project.

sharpImageService()

Type: (config?: SharpImageServiceConfig) => ImageServiceConfig

Added in: astro@2.4.1

Retrieves the Sharp service used to process Astro’s image assets. This takes an optional object describing the configuration options for Sharp.

validateConfig()

See validateConfig() in the Programmatic API reference.