Astro server-only import leaked into a client component in CI

Astro runs .astro frontmatter and endpoints on the server, but a framework component with a client: directive is bundled for the browser. Importing server-only code (a Node built-in, a DB client, secrets) into a client component fails the build or ships code the browser cannot run.

What this error means

The build fails resolving a Node built-in in a client component, or a hydrated component throws at runtime referencing server-only APIs.

[vite] Could not resolve "node:fs" imported by
"src/components/Cart.tsx" (a client:load component).
Node built-ins are not available in the browser.

Common causes

A client component imports server-only modules

A component with client:load/client:visible imports a DB client, a secrets helper, or a Node built-in, which cannot run in the browser.

Server data fetched in the client instead of frontmatter

Data that should be fetched in .astro frontmatter (server) is instead imported into the hydrated component.

How to fix it

Fetch on the server, pass props to the client

1. Do server work in .astro frontmatter or an endpoint.
2. Pass only the resulting data as props into the client component.
3. Keep Node built-ins and secrets out of any client: component.

---
import Cart from "../components/Cart.tsx";
const items = await db.getCart(); // server
---
<Cart client:load items={items} />

Move server logic to an endpoint

Expose server data through an API route and fetch it from the client instead of importing server modules directly.

How to prevent it

• Do server work in .astro frontmatter or endpoints, not client components.
• Never import Node built-ins or secrets into a client: component.
• Pass server data down as props.

Related guides