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, 6.x, or 7.x
- Node.js: 22.12.0 or higher (project-wide minimum for all supported Astro versions)
- TypeScript: 5.9.x or 6.x (
astro checkdoes not support TypeScript 7 yet)
Astro 5.x and 6.x are still supported by this plugin, but they use the same Node.js 22.12.0+ baseline as Astro 7.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 |
| 2.x | 5.x | >=22.12.0 | Active |
| 2.x | 6.x | >=22.12.0 | Active |
| 2.x | 7.x | >=22.12.0 | Active |
Astro Version Selection
When initializing the plugin, you can specify which major Astro version to install:
# Install with Astro 7.x (default)
nx g @geekvetica/nx-astro:init
# Install with Astro 7.x explicitly
nx g @geekvetica/nx-astro:init --astro-version=7
# Install with Astro 6.x
nx g @geekvetica/nx-astro:init --astro-version=6
# Install with Astro 5.x
nx g @geekvetica/nx-astro:init --astro-version=5
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 6 to Astro 7
If you have an existing project using Astro 6 and want to upgrade to Astro 7:
-
Update your workspace dependencies:
pnpm add -D astro@^7.3.6 @astrojs/node@^11.1.7Update any other
@astrojs/*integrations to their Astro 7 compatible majors as well. -
Node.js requirement is unchanged (22.12.0+)
-
Key breaking changes in Astro 7:
- Vite 8 (check Vite plugin compatibility)
- Rust-based compiler replaces the Go compiler and is stricter about invalid HTML (e.g. unclosed tags now error). Remove
experimental.rustCompilerif set. compressHTMLdefaults to'jsx'. SetcompressHTML: trueto keep the previous HTML-aware whitespace handling.- Markdown is rendered by Sätteri by default. To keep remark/rehype plugins, install
@astrojs/markdown-remarkand setmarkdown.processor: unified(). - Advanced routing is stable and uses
src/fetch.tsas its entrypoint. Moveexperimental.advancedRouting.fetchFileto the top-levelfetchFileoption (or setfetchFile: nullto disable it). @astrojs/dband theastro db/astro login/astro linkCLI commands are removed.- Deprecated
astro:transitionshelpers (TRANSITION_*constants,isTransition*Event(),createAnimationScope()) are removed.
-
astro devnow detaches into the background when an AI coding agent is detected. The nx-astrodevexecutor keeps the server in the foreground (it setsASTRO_DEV_BACKGROUND=0) so Nx can supervise it. SetASTRO_DEV_BACKGROUND=1yourself to opt back in.
Migrating from Astro 5 to Astro 6
If you have an existing project using Astro 5 and want to upgrade to Astro 6:
-
Update your workspace dependencies:
pnpm add -D astro@^6.2.0 @astrojs/node@^10.0.0 -
Ensure Node.js version is 22.12.0 or higher
-
Update content collections to use the Content Layer API (legacy collections are removed in Astro 6)
-
If you need a migration helper, enable the legacy compatibility flag in your
astro.config.mjs:export default defineConfig({ legacy: { collectionsBackwardsCompat: true, }, }); -
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 (useimport.meta.glob()instead)- CJS config files removed (use
.mjsor.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.