Content Collections strictMode enforcement changes CI failure semantics in Astro v2.0 migration

Direct answer

Astro v2.0 stabilizes Content Collections and makes strictMode a per-collection build gate. With strictMode: true schema violations are compile-time errors that exit the build with a non-zero code and stop CI. With strictMode: false or omitted, the same violations are emitted as warnings and the build continues.

There is no native phased mode that validates in development but allows production builds to succeed. The strictMode setting is global per collection and applies in both astro dev and astro build. Custom Vite Markdown/MDX plugins can coexist with the collection loader, but ordering matters. When strictMode is disabled, a schema that references an unresolvable type will not fail the build; the collection will load and components will receive undefined or partially parsed data at runtime.

Confirmed facts

• Content Collections moved from experimental content config to stable collections config in Astro v2.0.
• strictMode is defined per collection in astro.config.mjs and controls whether Zod validation errors are hard failures.
• Enabling strictMode mid-migration will break CI if existing content does not conform to the new schemas.

Likely explanation and practical constraints

The collection loader runs in Astro’s internal file pipeline. Legacy remark/rehype Vite plugins that mutate Markdown/MDX source after the loader has parsed frontmatter can cause race conditions or silent data loss. This is not a documented API guarantee and behavior depends on plugin order.

Unresolved types with strictMode disabled are likely to surface as runtime errors in components rather than build errors. The loader still attempts to parse the file, but validation is skipped, so bad data propagates.

Minimal steps for this migration case

1. Migrate config from experimental content to stable collections and define Zod schemas for each collection.
2. Keep strictMode: false in CI during the transition. Run a local validation pass with strictMode: true in development.
3. Environment-gate the flag if you need a temporary split, e.g. set it based on import.meta.env.DEV. This is a workaround, not a supported phased rollout.
4. Audit Vite plugins that touch .md/.mdx. Log transform order to confirm they run before the Astro collection loader parses frontmatter.
5. Fix all schema violations, then enable strictMode: true per collection before merging to main.

Verification: set strictMode: true on a test collection, introduce an invalid frontmatter field, and confirm astro build exits non-zero. Check plugin order by logging file IDs in a custom Vite plugin.

Uncertainty note: Astro’s major versioning after v2 changed Content Collections APIs and defaults. Current verification is required for the exact version you are on, as strictMode semantics and loader internals have evolved.