nx-astro

Nx plugin for Astro - Build fast websites with Astro in an Nx monorepo

Features

• Automatic Task Inference - Detects Astro projects and configures tasks automatically
• Code Generators - Scaffold applications and components with ease
• Full TypeScript Support - Type-safe configuration and development
• Nx Caching - Lightning-fast builds with intelligent caching
• Content Collections - First-class support for Astro content collections
• SSR Support - Build static sites or server-rendered applications
• Testing Integration - Built-in Vitest support for unit and integration tests

Quick Start

Installation

# Create a new Nx workspace
npx create-nx-workspace@latest my-workspace

# Install nx-astro
cd my-workspace
npm install --save-dev @geekvetica/nx-astro

# Initialize the plugin
nx g @geekvetica/nx-astro:init

Create Your First Application

# Generate an Astro application
nx g @geekvetica/nx-astro:application my-app

# Start development server
nx dev my-app

# Build for production
nx build my-app

Create Components

# Generate a component
nx g @geekvetica/nx-astro:component Button --project=my-app

# Generate a component in a subdirectory
nx g @geekvetica/nx-astro:component Card --project=my-app --directory=ui

Available Commands

Once you have an Astro application in your workspace, you can run these commands:

# Development
nx dev my-app              # Start dev server with HMR
nx dev my-app --port=3000  # Custom port

# Building
nx build my-app            # Production build
nx build my-app --verbose  # Verbose output

# Preview
nx preview my-app          # Preview production build

# Type Checking
nx check my-app            # Run type checking
nx check my-app --watch    # Watch mode

# Testing
nx test my-app             # Run tests
nx test my-app --coverage  # With coverage

# Content Collections
nx sync my-app             # Generate content types

Monorepo Workflows

The plugin integrates seamlessly with Nx monorepo features:

# Run tasks for multiple projects
nx run-many --target=build --projects=app1,app2,app3

# Build all projects
nx run-many --target=build --all

# Build only affected projects (based on git changes)
nx affected --target=build

# View project graph
nx graph

Templates

Choose from starter templates when creating applications:

• minimal - Basic starter with essential files
• blog - Blog template with content collections
• portfolio - Portfolio template for showcasing projects

nx g @geekvetica/nx-astro:application my-blog --template=blog
nx g @geekvetica/nx-astro:application my-portfolio --template=portfolio

Importing Existing Projects

Migrate existing Astro projects into your Nx workspace with the import generator:

# Import from a local path
nx g @geekvetica/nx-astro:import --source=../my-astro-app

# Import with custom name and directory
nx g @geekvetica/nx-astro:import --source=./external/astro-site --name=my-site --directory=apps/websites

# Import with tags for organization
nx g @geekvetica/nx-astro:import --source=/path/to/app --tags=astro,web,public-facing

# Import with custom TypeScript path alias
nx g @geekvetica/nx-astro:import --source=../app --name=my-app --importPath=@myorg/my-app

The import generator automatically:

• Validates the source is a valid Astro project
• Copies all project files (excluding node_modules, build outputs, etc.)
• Creates Nx project configuration with all standard targets (dev, build, preview, check, sync)
• Updates TypeScript path mappings in tsconfig.base.json
• Registers the project in your workspace

After importing:

# Install dependencies
pnpm install

# Start development
nx dev my-site

# Build for production
nx build my-site

Configuration

Plugin Configuration

Configure the plugin in nx.json:

{
  "plugins": [
    {
      "plugin": "@geekvetica/nx-astro",
      "options": {
        "devTargetName": "dev",
        "buildTargetName": "build",
        "checkTargetName": "check"
      }
    }
  ]
}

Project Configuration

The plugin automatically infers tasks from astro.config.mjs. To customize, create a project.json:

{
  "name": "my-app",
  "targets": {
    "dev": {
      "executor": "@geekvetica/nx-astro:dev",
      "options": {
        "port": 3000,
        "host": true
      }
    },
    "build": {
      "executor": "@geekvetica/nx-astro:build",
      "options": {
        "outputPath": "dist/apps/my-app",
        "site": "https://example.com"
      }
    }
  }
}

Shared Libraries

Create shared component libraries for use across multiple Astro apps:

# Create shared library
nx g @nx/js:library shared-ui --directory=libs/shared-ui

# Configure path aliases in tsconfig.base.json
{
  "compilerOptions": {
    "paths": {
      "@my-org/shared-ui/*": ["libs/shared-ui/src/*"]
    }
  }
}

# Use in any Astro app
import Button from '@my-org/shared-ui/components/Button.astro';

Content Collections

Full support for Astro content collections with type generation:

// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    pubDate: z.date(),
    description: z.string(),
  }),
});

export const collections = { blog };

# Generate types
nx sync my-app

# Types are now available
import { getCollection } from 'astro:content';
const posts = await getCollection('blog'); // Fully typed!

SSR Support

Build server-rendered applications:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
});

nx build my-app
node dist/apps/my-app/server/entry.mjs

Testing

The plugin includes Vitest configuration for testing:

// src/components/Button.test.ts
import { experimental_AstroContainer as AstroContainer } from 'astro/container';
import Button from './Button.astro';

test('renders button', async () => {
  const container = await AstroContainer.create();
  const result = await container.renderToString(Button, {
    slots: { default: 'Click me' },
  });
  expect(result).toContain('Click me');
});

nx test my-app
nx test my-app --coverage
nx test my-app --watch

Performance

Nx caching dramatically improves build times:

# First build (cold)
nx build my-app
# ✓ Built in 15.3s

# Second build (cached)
nx build my-app
# ✓ Nx read the output from the cache (0.2s)

CI/CD Integration

Optimize your CI pipeline with affected detection:

# .github/workflows/ci.yml
- name: Build affected projects
  run: nx affected --target=build --base=origin/main

- name: Test affected projects
  run: nx affected --target=test --base=origin/main

Documentation

Guides

• Generators Guide - Create projects and components
• Executors Guide - Run dev servers, builds, and tests
• Configuration Guide - Configure the plugin and projects
• Migration Guide - Migrate existing Astro projects
• Examples - Real-world usage examples

Reference

• API Reference - Complete schemas and types
• FAQ - Frequently asked questions
• Troubleshooting - Common issues and solutions

Setup

• CI/CD Setup Guide - Configure continuous integration
• E2E Testing Guide - End-to-end testing setup
• Architecture - Technical architecture overview

Requirements

• Nx: 21.6.4 or higher
• Astro: 5.x or 6.x
• Node.js: 22.12.0 or higher (project-wide minimum for all supported Astro versions)
• TypeScript: 5.9.0 or higher

Astro 5.x is still supported by this plugin, but it uses the same Node.js 22.12.0+ baseline as Astro 6.x.

Version Support

| nx-astro | Astro | Node.js | Status | | -------- | ----- | --------- | ------ | | 1.x | 5.x | >=22.12.0 | Active | | 1.x | 6.x | >=22.12.0 | Active |

Astro Version Selection

When initializing the plugin, you can specify which major Astro version to install:

# Install with Astro 6.x (default)
nx g @geekvetica/nx-astro:init

# Install with Astro 5.x
nx g @geekvetica/nx-astro:init --astro-version=5

# Install with Astro 6.x explicitly
nx g @geekvetica/nx-astro:init --astro-version=6

The plugin will automatically detect an existing Astro installation and use that version range.

Note: regardless of Astro major version selection, this plugin requires Node.js 22.12.0 or higher.

Migrating from Astro 5 to Astro 6

If you have an existing project using Astro 5 and want to upgrade to Astro 6:

1. Update your workspace dependencies:

   pnpm add -D astro@^6.2.0 @astrojs/node@^10.0.0

2. Ensure Node.js version is 22.12.0 or higher

3. Update content collections to use the Content Layer API (legacy collections are removed in Astro 6)

4. If you need a migration helper, enable the legacy compatibility flag in your astro.config.mjs:

   export default defineConfig({
     legacy: {
       collectionsBackwardsCompat: true,
     },
   });

5. Key breaking changes in Astro 6:

   • Node 18/20 support dropped (requires Node 22.12.0+)
   • Vite 7.0 (check Vite plugin compatibility)
   • Zod 4.0 (update content schemas if using custom validation)
   • Astro.glob() removed (use import.meta.glob() instead)
   • CJS config files removed (use .mjs or .ts)
   • Legacy content collections removed (migrate to Content Layer API)

Generators

| Generator | Description | | ------------- | ----------------------------------------------- | | init | Initialize the nx-astro plugin | | application | Create a new Astro application from a template | | import | Import an existing Astro project into workspace | | component | Generate an Astro component |

Executors

| Executor | Description | | --------- | --------------------------------- | | dev | Run development server with HMR | | build | Build for production | | preview | Preview production build | | check | Run TypeScript type checking | | test | Run Vitest tests | | sync | Generate content collection types |

Examples

Monorepo with Multiple Sites

my-workspace/
├── apps/
│   ├── marketing/      # Main website
│   ├── blog/           # Company blog
│   └── docs/           # Documentation
└── libs/
    └── shared-ui/      # Shared components

# Build all sites
nx run-many --target=build --all

# Run dev servers with different ports
nx dev marketing  # port 4321
nx dev blog       # port 4322
nx dev docs       # port 4323

Blog with Content Collections

# Create blog
nx g @geekvetica/nx-astro:application my-blog --template=blog

# Generate types for content
nx sync my-blog

# Add posts to src/content/blog/
# Types are automatically updated

Shared Component Library

# Create library
nx g @nx/js:library shared-ui

# Add components
# libs/shared-ui/src/components/Button.astro
# libs/shared-ui/src/components/Card.astro

# Use in apps
import { Button, Card } from '@my-org/shared-ui';

Community

• GitHub: Report issues
• Discussions: Ask questions
• Nx Community: Join Discord
• Astro Community: Join Discord

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

MIT © Geekvetica Paweł Wojciechowski

Support

Having issues? Check the Troubleshooting Guide or open an issue.

Changelog

See releases for version history.