sync()

Generate TypeScript types for Astro modules and content collections

The sync() function generates TypeScript types for all Astro modules in your project. This sets up a src/env.d.ts file for type inferencing and defines the astro:content module for the Content Collections API.

The JavaScript API is experimental and may change in future releases.

Import

import { sync } from 'astro';

Signature

function sync(inlineConfig: AstroInlineConfig): Promise<void>

Parameters

inlineConfig · AstroInlineConfig · required

Configuration object for your Astro project. Supports all options from astro.config.mjs.

inlineConfig.root · string

The root directory of your Astro project. Defaults to the current working directory.

inlineConfig.logLevel · 'debug' | 'info' | 'warn' | 'error' | 'silent' · default: "'info'"

Controls the verbosity of logging output.

inlineConfig.force · boolean · default: "false"

Force a clean sync by clearing the content layer cache before generating types.

Return Value

Returns a Promise<void> that resolves when type generation completes successfully.

What It Does

The sync() function performs the following tasks:

1. Generates src/env.d.ts: Creates TypeScript definitions for Astro’s built-in modules
2. Creates .astro/types.d.ts: Generates type definitions in your cache directory
3. Generates Content Collections types: Creates the astro:content module with types for your content collections
4. Syncs content layer: Updates the content layer cache with the latest content
5. Generates environment types: Creates types for environment variables defined in your schema

Examples

Basic Sync

import { sync } from 'astro';

await sync({
  root: './my-project',
});

console.log('Types generated!');

Force Clean Sync

Clear the cache and regenerate all types:

import { sync } from 'astro';

await sync({
  root: './my-project',
  force: true,
});

Silent Mode

import { sync } from 'astro';

await sync({
  root: './my-project',
  logLevel: 'silent',
});

Pre-Build Hook

Run sync before building to ensure types are up-to-date:

import { sync, build } from 'astro';

async function buildWithSync() {
  console.log('Generating types...');
  await sync({ root: '.' });

  console.log('Building site...');
  await build({ root: '.' });
}

buildWithSync();

Watch Script

Create a custom watch script that regenerates types on changes:

import { sync } from 'astro';
import { watch } from 'chokidar';

const contentDir = './src/content';

const watcher = watch(contentDir, {
  persistent: true,
  ignoreInitial: true,
});

watcher.on('all', async (event, path) => {
  console.log(`${event}: ${path}`);
  console.log('Regenerating types...');

  try {
    await sync({ root: '.', logLevel: 'silent' });
    console.log('Types updated!');
  } catch (error) {
    console.error('Type generation failed:', error);
  }
});

console.log(`Watching ${contentDir} for changes...`);

CI/CD Type Check

import { sync } from 'astro';
import { exec } from 'node:child_process';
import { promisify } from 'node:util';

const execAsync = promisify(exec);

async function typeCheck() {
  try {
    // Generate types
    console.log('Generating types...');
    await sync({ root: '.' });

    // Run TypeScript compiler
    console.log('Running type check...');
    const { stdout, stderr } = await execAsync('tsc --noEmit');

    if (stderr) {
      console.error('Type errors found:');
      console.error(stderr);
      process.exit(1);
    }

    console.log('Type check passed!');
  } catch (error) {
    console.error('Type check failed:', error);
    process.exit(1);
  }
}

typeCheck();

Content Collections Sync

Ensure content collection types are generated before running tests:

import { sync } from 'astro';

// In your test setup
before(async () => {
  await sync({
    root: './test-fixtures/content-collections',
    logLevel: 'silent',
  });
});

Multiple Projects

import { sync } from 'astro';

const projects = [
  './packages/site-1',
  './packages/site-2',
  './packages/site-3',
];

async function syncAll() {
  for (const project of projects) {
    console.log(`Syncing ${project}...`);
    await sync({ root: project });
  }
  console.log('All projects synced!');
}

syncAll();

Error Handling

import { sync } from 'astro';

async function safeSync() {
  try {
    await sync({ root: './my-project' });
    console.log('Successfully generated types');
  } catch (error) {
    if (error.message.includes('content config')) {
      console.error('Content configuration error:', error.message);
    } else {
      console.error('Sync failed:', error);
    }
    process.exit(1);
  }
}

safeSync();

Development Workflow

import { sync, dev } from 'astro';

async function devWithSync() {
  // First sync to generate types
  console.log('Generating types...');
  await sync({ root: '.' });

  // Then start dev server
  console.log('Starting dev server...');
  const server = await dev({ root: '.' });

  console.log(`Dev server running at http://localhost:${server.address.port}`);
}

devWithSync();

Monorepo Setup

import { sync } from 'astro';
import { glob } from 'glob';

async function syncWorkspaces() {
  // Find all Astro projects in the monorepo
  const astroConfigs = await glob('packages/*/astro.config.{mjs,js,ts}');

  const projects = astroConfigs.map((config) =>
    config.replace(/\/astro\.config\.[^/]+$/, '')
  );

  console.log(`Found ${projects.length} Astro projects`);

  // Sync all projects in parallel
  await Promise.all(
    projects.map((project) => {
      console.log(`Syncing ${project}...`);
      return sync({ root: project, logLevel: 'silent' });
    })
  );

  console.log('All workspaces synced!');
}

syncWorkspaces();

When to Use

You should run sync() when:

• Adding or modifying content collections
• Adding or changing content schemas
• Setting up a new project
• After pulling changes that affect content
• Before running type checks in CI/CD
• When content collection types are out of date

Related

• build() - Build for production
• dev() - Start development server
• preview() - Preview production build