Nx Astro Plugin

@surkyl/nx-astro

Nx plugin for Astro and Starlight applications.

Features

🚀 Generate Astro applications with various templates
📚 Generate Starlight documentation sites
⚡️ Support for React, Vue, Svelte, Solid, and Preact
🎨 Tailwind CSS and SCSS support
📝 TypeScript support
🔧 ESLint and Prettier configuration
🎯 Content Collections support
🐳 Docker support with multi-stage builds
🏗️ Complete Nx integration with Docker targets

Installation

pnpm add -D @surkyl/nx-astro

Generators

Astro Application

Generate a new Astro application:

nx g @surkyl/nx-astro:astro my-site

Options:

--template - Template to use (minimal, blog, portfolio, docs)
--port - Development server port (default: 4321)
--typescript - Use TypeScript (default: true)
--styling - Styling approach (css, scss, tailwind)
--framework - UI framework (none, react, vue, svelte, solid, preact)
--contentCollections - Include content collections (default: true)
--eslint - Add ESLint (default: true)
--prettier - Add Prettier (default: true)
--docker - Include Docker configuration (default: false)
--dockerRegistry - Docker registry for images (e.g., myorg, ghcr.io/myorg)

Example:

# Basic Astro app
nx g @surkyl/nx-astro:astro my-blog \
  --template=blog \
  --framework=react \
  --styling=tailwind

# With Docker support
nx g @surkyl/nx-astro:astro my-site \
  --docker \
  --dockerRegistry=myorg

Starlight Documentation

Generate a new Starlight documentation site:

nx g @surkyl/nx-astro:starlight my-docs

Options:

--title - Site title
--port - Development server port (default: 4322)
--typescript - Use TypeScript (default: true)
--i18n - Enable internationalization
--sidebar - Include sidebar navigation (default: true)
--search - Enable search (default: true)
--editLink - Include edit page links
--socialLinks - Include social media links
--customCss - Include custom CSS file
--docker - Include Docker configuration (default: false)
--dockerRegistry - Docker registry for images

Example:

nx g @surkyl/nx-astro:starlight api-docs \
  --title="API Documentation" \
  --i18n \
  --search

Executors

Dev

Start the development server:

nx dev my-site

Options:

--port - Port number
--host - Host address
--open - Open browser automatically

Build

Build for production:

nx build my-site

Preview

Preview the production build:

nx preview my-site

Options:

--port - Port number
--host - Host address

Check

Run type checking:

nx check my-site

Options:

--watch - Watch for changes

Docker Support

When you generate an app with --docker flag, you get:

Dockerfile - Multi-stage build optimized for production
docker-compose.yml - Container orchestration configuration
.dockerignore - Optimized Docker ignore rules
Docker Nx targets - Integrated Docker commands

Docker Targets

All Docker operations are available as Nx targets:

# Build Docker image
nx docker-build my-site

# Start container with Docker Compose
nx docker-compose-up my-site

# Stop container
nx docker-compose-down my-site

# Start existing container
nx docker-start my-site

# Stop running container
nx docker-stop my-site

# Tag image with git info
nx docker-tag my-site

# Push to registry
nx docker-push my-site

Docker Example Workflow

Generate app with Docker support:

nx g @surkyl/nx-astro:astro my-app \
  --framework=react \
  --styling=tailwind \
  --docker \
  --dockerRegistry=ghcr.io/myorg

Build the Docker image:
Terminal window
```
nx docker-build my-app
```
Run with Docker Compose:
Terminal window
```
nx docker-compose-up my-app
```

Push to registry:

nx docker-tag my-app
nx docker-push my-app

Example Workflow

Generate an Astro site with React and Tailwind:

nx g @surkyl/nx-astro:astro my-app --framework=react --styling=tailwind

Start development:
Terminal window
```
nx dev my-app
```
Build for production:
Terminal window
```
nx build my-app
```
Preview the build:
Terminal window
```
nx preview my-app
```

Learn More

License

MIT