Guide

Set up Content Collections

Generate a local, REST, GraphQL, Strapi or Shopify example and configure when it loads.

Choose a source and a loading time

When you select Content, the wizard asks for the source, a collection name and when the data should load. An API can be read during a static build; live reads need request-time execution through an adapter.

SourceGenerated starting example
Local filesOffline JSON data, schema and active collection registration.
APIA REST or GraphQL response contract, query and bounded requests.
StrapiStrapi 5 published/localized documents and pagination.
ShopifyA read-only Storefront products query with cursor pagination.
Other serviceA named REST or GraphQL example to adapt to that service.

Only the chosen source’s example is added. You can add another collection later under a different name.

Add a local collection

From the generated project root:

npm

Terminal
npx @samline/astro add content --source local --collection articles

pnpm

Terminal
pnpm dlx @samline/astro add content --source local --collection articles

Bun

Terminal
bunx @samline/astro add content --source local --collection articles

This creates src/content/articles with sample data and a schema, and registers articles in src/content.config.ts. The adjacent README shows how to read the sample and resolve its copyKey through the content dictionary. It works offline.

Local files use build-time collections. Add your real content and schema in that folder, then render it from the section that owns the content.

Prepare a remote collection

Choose the command for your actual source; these are independent alternatives:

npm

Terminal
npx @samline/astro add content --source strapi --collection news --content-mode build
npx @samline/astro add content --source api --protocol rest --collection updates --content-mode live
npx @samline/astro add content --source shopify --collection products
npx @samline/astro add content --source other --service 'Custom CMS' --protocol graphql --collection stories

pnpm

Terminal
pnpm dlx @samline/astro add content --source strapi --collection news --content-mode build
pnpm dlx @samline/astro add content --source api --protocol rest --collection updates --content-mode live
pnpm dlx @samline/astro add content --source shopify --collection products
pnpm dlx @samline/astro add content --source other --service 'Custom CMS' --protocol graphql --collection stories

Bun

Terminal
bunx @samline/astro add content --source strapi --collection news --content-mode build
bunx @samline/astro add content --source api --protocol rest --collection updates --content-mode live
bunx @samline/astro add content --source shopify --collection products
bunx @samline/astro add content --source other --service 'Custom CMS' --protocol graphql --collection stories

The live example requires a server-capable deployment. Each remote collection gets index.ts, source.ts, loader.ts, types.ts, .env.example and a README inside src/content/<collection-name>. Installation prepares these files without calling the provider.

Before activating a remote example:

  1. Copy its environment variable names to the project’s ignored environment or hosting settings, and supply the real URL, endpoint and token as needed.
  2. Adapt source.ts to the provider’s actual fields and response schema.
  3. Review the explicit locale map in index.ts against the provider’s language codes.
  4. Follow the registration instructions in the generated README, then run the project checks with its real source configured.

For build-time data, merge the adjacent registration.ts.example into src/content.config.ts. For live data, merge or rename src/live.config.ts.example to src/live.config.ts. Preserve other registered collections when merging.

The Shopify example reads products through the Storefront API. Cart, checkout, Admin API and customer accounts are separate application work. The Other option supplies a custom-service starting point whose API contract you adapt yourself.

Read at the right time

Build-time collections are read while Astro builds the site; upstream changes appear after another build. Live Collections are read in a request-time consumer, such as a server-rendered route or Server Island. A static parent page can remain static while its island loads current data.

The generated collection README includes the appropriate read example. Keep content UI in its section and use real translation relationships when content slugs differ between languages.

Choose the rendering boundary per route and block. A static listing with a live Server Island can coexist with an on-demand detail route when that detail needs current data and individual metadata in its initial HTML. With a compatible adapter, the project’s detail route can opt out of prerendering while other pages stay static. Resolve one validated result for both metadata and visible content; reuse related data already returned rather than issuing duplicate reads.

Choose Actions, Live Collections or a private server function for the actual consumer/transport contract; none is mandatory for every API. Define missing, unavailable and partial-data behavior with real status codes and cache policies. Keep identity in the canonical URL while excluding incidental navigation context, and explicitly provide discoverable detail URLs/sitemap entries where required. Do not assume a static sitemap enumerates runtime records or that a large catalogue alone requires changing the entire site’s rendering mode.

See Astro’s on-demand rendering guide for the framework configuration. This is a project decision, not a change to the starter’s static default.

For the framework APIs, continue with Astro’s Content Collections and Content Loader API.