@geekvetica/nx-astro

中文文档
3.0.4发布于 2026/11/09MITTypeScriptCommonJS构建来源已验证近 30 天下载 4996

An Nx plugin for Astro that provides generators and executors for seamless integration of Astro applications in Nx monorepos

原始使用文档
文档目录38 节
  1. Features
  2. Quick Start
  3. Installation
  4. Create Your First Application
  5. Create Components
  6. Available Commands
  7. Monorepo Workflows
  8. Templates
  9. Importing Existing Projects
  10. Configuration
  11. Plugin Configuration
  12. Project Configuration
  13. Shared Libraries
  14. Content Collections
  15. SSR Support
  16. Testing
  17. Performance
  18. CI/CD Integration
  19. Documentation
  20. Guides
  21. Reference
  22. Setup
  23. Requirements
  24. Version Support
  25. Astro Version Selection
  26. Migrating from Astro 6 to Astro 7
  27. Migrating from Astro 5 to Astro 6
  28. Generators
  29. Executors
  30. Examples
  31. Monorepo with Multiple Sites
  32. Blog with Content Collections
  33. Shared Component Library
  34. Community
  35. Contributing
  36. License
  37. Support
  38. Changelog

nx-astro

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

npm version License: MIT

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

Reference

Setup

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 check does 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-astroAstroNode.jsStatus
1.x5.x>=22.12.0Active
1.x6.x>=22.12.0Active
2.x5.x>=22.12.0Active
2.x6.x>=22.12.0Active
2.x7.x>=22.12.0Active

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:

  1. Update your workspace dependencies:

    pnpm add -D astro@^7.3.6 @astrojs/node@^11.1.7
    

    Update any other @astrojs/* integrations to their Astro 7 compatible majors as well.

  2. Node.js requirement is unchanged (22.12.0+)

  3. 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.rustCompiler if set.
    • compressHTML defaults to 'jsx'. Set compressHTML: true to keep the previous HTML-aware whitespace handling.
    • Markdown is rendered by Sätteri by default. To keep remark/rehype plugins, install @astrojs/markdown-remark and set markdown.processor: unified().
    • Advanced routing is stable and uses src/fetch.ts as its entrypoint. Move experimental.advancedRouting.fetchFile to the top-level fetchFile option (or set fetchFile: null to disable it).
    • @astrojs/db and the astro db / astro login / astro link CLI commands are removed.
    • Deprecated astro:transitions helpers (TRANSITION_* constants, isTransition*Event(), createAnimationScope()) are removed.
  4. astro dev now detaches into the background when an AI coding agent is detected. The nx-astro dev executor keeps the server in the foreground (it sets ASTRO_DEV_BACKGROUND=0) so Nx can supervise it. Set ASTRO_DEV_BACKGROUND=1 yourself 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:

  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

GeneratorDescription
initInitialize the nx-astro plugin
applicationCreate a new Astro application from a template
importImport an existing Astro project into workspace
componentGenerate an Astro component

Executors

ExecutorDescription
devRun development server with HMR
buildBuild for production
previewPreview production build
checkRun TypeScript type checking
testRun Vitest tests
syncGenerate 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

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.

版本与发布记录

@geekvetica/nx-astro 共发布 18 个版本,首次发布于 2025/10/15;过去 12 个月发布了 6 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
3.0.4latest2026/11/096 天前
3.0.32026/10/2026 天前
3.0.22026/10/151 个月前
3.0.12026/10/091 个月前
3.0.02026/10/081 个月前
2.0.02026/05/126 个月前

关于 @geekvetica/nx-astro 的常见问题

@geekvetica/nx-astro 是什么?

An Nx plugin for Astro that provides generators and executors for seamless integration of Astro applications in Nx monorepos

如何安装 @geekvetica/nx-astro?

在项目目录运行 npm install @geekvetica/nx-astro,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:nx(>=22.0.0 <24.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@geekvetica/nx-astro 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@geekvetica/nx-astro 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@geekvetica/nx-astro 可以商用吗?

@geekvetica/nx-astro 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@geekvetica/nx-astro 的下载量有多少?

根据 npm 官方下载统计,@geekvetica/nx-astro 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,996 次,日均约 167 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@geekvetica/nx-astro 还在维护吗?

最新版本 3.0.4 发布于 2026/11/09(6 天前);至今共发布 18 个版本,其中过去 12 个月发布了 6 个;首次发布于 2025/10/15。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。