astro

library0.2.7jsnpmunverified

Astro is a modern site builder with web best practices, performance, and developer experience at the forefront. The current stable version is 6.1.8, and it receives frequent patch updates with major versions typically released on an annual or bi-annual cadence.

web-framework

npm install astro

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ASTRO

astro

web-frameworkjavascriptv0.2.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

defineConfig

✓ import { defineConfig } from 'astro/config';

✗ import defineConfig from 'astro/config';

Used in `astro.config.mjs` or `astro.config.ts` for project configuration. It's a named export, not a default.

Image

✓ import { Image } from 'astro:assets';

✗ import Image from 'astro:assets';

This is a named import for Astro's built-in image optimization component, typically used in `.astro` components.

APIContext

✓ import type { APIContext } from 'astro';

✗ import { APIContext } from 'astro';

A TypeScript type used to define the context object passed to API routes and middleware. It should be imported as a type.

AstroUserConfig

✓ import type { AstroUserConfig } from 'astro/config';

✗ import { AstroUserConfig } from 'astro/config';

A TypeScript type for configuring Astro, often used with `defineConfig` for enhanced type safety in `astro.config.ts`.

This `astro.config.ts` example demonstrates how to configure an Astro project, including adding an integration like React and setting the site URL. It showcases the use of `defineConfig` for type-safe configuration.

import { defineConfig } from 'astro/config'; import react from '@astrojs/react'; export default defineConfig({ integrations: [react()], site: 'https://example.com', });

astro --version

Debug

Known issues

breakingAstro v6.0 and later require Node.js version 22.12.0 or higher. Node.js versions 18 and 20 are no longer supported.

fix

Upgrade your Node.js environment to version 22.12.0 or newer. Check your hosting and CI environments.

affects: >=6.0.0

breakingThe `Astro.glob()` API was removed in Astro v6.0.0.

fix

Migrate to `import.meta.glob()` for dynamic file imports. This Vite-powered API offers similar functionality but with differences in return type and static analysis limitations.

affects: >=6.0.0

breakingAstro v6.0.0 updated its internal Zod dependency to v4. Projects directly using Zod for schema validation (e.g., in content collections or API routes) may require updates.

fix

Review the Zod v4 migration guide and update your schemas as needed.

affects: >=6.0.0

breakingAstro v6.0.0 removed support for legacy content collections and the `legacy.collections` flag. All content collections must now use the Content Layer API.

fix

Migrate any existing legacy content collections to the Content Layer API introduced in Astro v5.0.

affects: >=6.0.0

gotchaAccessing browser-specific objects like `document` or `window` in Astro components' frontmatter or server-rendered framework components will result in errors.

fix

Move client-side code to a `<script>` tag outside the frontmatter, or use client directives (`client:load`, `client:idle`, `client:visible`, `client:media`, `client:only`) on framework components to ensure code runs in the browser.

affects: >=1.0.0

gotchaWhen using the `client:only` directive on a UI framework component, you must explicitly specify the framework (e.g., `client:only="react"`). Astro skips server-side rendering and needs to know the target framework.

fix

Add the framework identifier as the value for `client:only`, such as `<MyReactComponent client:only="react" />`.

affects: >=1.0.0

Errors

Common errors & fixes

SyntaxError: Unexpected token 'with'

Your Node.js version is too old for the Astro version you are using.

fix

Upgrade Node.js to version 22.12.0 or newer.

TypeError: Cannot read properties of undefined (reading 'split')

This often occurs when an environment variable or a package expects a string but receives `undefined` or a non-string value, or due to internal issues with Vite's environment variable processing.

fix

Ensure all environment variables being accessed are defined and are of the expected type (string). For older Astro versions, certain characters in `.env` could cause issues; update Astro to the latest patch.

document is not defined (or window is not defined)

You are attempting to access browser-specific APIs (`document`, `window`) in an Astro component's frontmatter or in a framework component that is being server-rendered.

fix

Move the code that accesses browser APIs into a `<script>` tag in an `.astro` component, or apply a client directive (e.g., `client:load`, `client:only`) to your UI framework component to defer its execution to the client.

Cannot find module 'X' / ERR_MODULE_NOT_FOUND

A dependency is missing, incorrectly installed, or the import path is wrong. This can also happen if a package is incompatible with Astro's build process.

fix

Verify the package is installed (`npm install X`). Check the import path for typos. Delete `node_modules` and `package-lock.json` (or equivalent) and reinstall dependencies. Consult the Astro documentation for known incompatible packages.

import.meta.glob() did not match any files / import.meta.glob() cannot take variables

The glob pattern provided to `import.meta.glob()` is incorrect, does not match any files, or contains dynamic variables/string interpolation which is not supported due to a limitation of Vite.

fix

Ensure the glob pattern accurately reflects the file paths. `import.meta.glob()` requires static string literals. For dynamic paths, import a larger set of files and then filter them, or manually construct imports if the set is small and known.

Upgrade

Version history

0.2.7latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/withastro/astro ↗

packagehttps://www.npmjs.com/package/astro ↗

homepagehttps://astro.build ↗