npm package: @ludena-studio/nx-astro
Description: Nx plugin for Astro integration
Author: Ludena Studio
Latest version: 1.0.0

# @ludena-studio/nx-astro

Official Nx plugin by Ludena Studio for seamless [Astro](https://astro.build) integration in Nx monorepos.

[![npm version](https://badge.fury.io/js/@ludena-studio%2Fnx-astro.svg)](https://www.npmjs.com/package/@ludena-studio/nx-astro)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- ✨ **Generators** - Scaffold Astro applications with optimized Nx configuration
- ⚡ **Executors** - Run `dev`, `build`, `preview`, and manage integrations
- 🔄 **Smart Caching** - Leverage Nx's intelligent caching system
- 🏗️ **Production Ready** - Robust validation, logging, and error handling
- 🧪 **96% Test Coverage** - Comprehensive unit tests and edge cases

## Installation

```bash
npm install --save-dev @ludena-studio/nx-astro astro
# or
pnpm add -D @ludena-studio/nx-astro astro
# or
yarn add -D @ludena-studio/nx-astro astro
```

## Quick Start

### 1. Generate an Astro Application

```bash
nx g @ludena-studio/nx-astro:app my-astro-app
```

This creates a new Astro app with:
- Optimized Nx project configuration
- TypeScript support
- Pre-configured executors for dev, build, and preview
- Ready-to-use project structure

### 2. Available Commands

```bash
# Start development server
nx dev my-astro-app

# Build for production
nx build my-astro-app

# Preview production build
nx preview my-astro-app

# Add Astro integrations
nx add my-astro-app --integration=tailwind
nx add my-astro-app --integration=react
nx add my-astro-app --integration=mdx
```

## Package Manager Support

The plugin **automatically detects** your workspace's package manager (npm, pnpm, yarn, or bun) and configures the generated `.gitignore` accordingly to ignore the appropriate lockfile:

- **npm** → ignores `package-lock.json`
- **pnpm** → ignores `pnpm-lock.yaml`
- **yarn** → ignores `yarn.lock`
- **bun** → ignores `bun.lockb`

This ensures that generated projects respect your workspace configuration without manual adjustments.

## Generators

### `app` - Create Astro Application

```bash
nx g @ludena-studio/nx-astro:app <name> [options]
```

**Options:**
- `--directory` - Directory where the app will be created
- `--tags` - Tags to categorize the project
- `--strict` - Enable strict TypeScript mode (default: `true`)
- `--mdx` - Include MDX integration with automatic dependency installation (default: `true`)
- `--tailwind` - Include Tailwind CSS integration with config files and setup (default: `false`)

**Examples:**
```bash
# Basic app
nx g @ludena-studio/nx-astro:app my-app

# App with MDX and Tailwind CSS (automatically installs dependencies)
nx g @ludena-studio/nx-astro:app my-blog --mdx --tailwind

# Organized in a custom directory
nx g @ludena-studio/nx-astro:app my-site --directory=apps/marketing --tags=public
```

#### Integrations

When you enable **MDX** or **Tailwind CSS**, the generator automatically:

**MDX Integration (`--mdx`):**
- ✅ Installs `@astrojs/mdx` dependency
- ✅ Configures MDX in `astro.config.mjs`
- ✅ Ready to use `.mdx` files immediately

**Tailwind CSS Integration (`--tailwind`):**
- ✅ Installs `tailwindcss` (v4+) and `@tailwindcss/vite` dependencies
- ✅ Configures Tailwind using the **Vite plugin** in `astro.config.mjs` (recommended for Tailwind 4)
- ✅ Generates `src/styles/global.css` with Tailwind 4 import syntax
- ✅ Imports global styles in your pages
- ✅ No `tailwind.config.mjs` needed (Tailwind 4 uses CSS-first configuration)

No manual setup required—everything is configured and ready to use!

## Executors

### `dev` - Development Server

Start the Astro development server with hot module replacement.

```bash
nx dev <project> [options]
```

**Options:**
- `--port` - Port number (default: 4321)
- `--host` - Hostname or `true` for 0.0.0.0
- `--open` - Open browser on start (boolean or URL path)

**Example:**
```bash
nx dev my-astro-app --port 3000 --host --open
```

### `build` - Production Build

Build your Astro site for production deployment.

```bash
nx build <project> [options]
```

**Options:**
- `--outputPath` - Custom output directory

**Example:**
```bash
nx build my-astro-app
```

### `preview` - Preview Build

Preview your production build locally before deployment.

```bash
nx preview <project> [options]
```

**Options:**
- `--port` - Port number (default: 4321)
- `--host` - Hostname or `true` for 0.0.0.0

**Example:**
```bash
nx preview my-astro-app --port 8080
```

### `add` - Add Integration

Add official Astro integrations to your project.

```bash
nx add <project> --integration=<name> [options]
```

**Options:**
- `--integration` (required) - Integration name (e.g., tailwind, react, vue)
- `--yes` - Skip confirmation prompts

**Example:**
```bash
nx add my-astro-app --integration=tailwind --yes
nx add my-astro-app --integration=react
```

## Advanced Configuration

### Custom Executor Options

You can customize executor behavior in your `project.json`:

```json
{
  "targets": {
    "dev": {
      "executor": "@ludena-studio/nx-astro:dev",
      "options": {
        "port": 3000,
        "host": true,
        "open": true
      }
    },
    "build": {
      "executor": "@ludena-studio/nx-astro:build",
      "options": {
        "outputPath": "dist/apps/my-app"
      },
      "outputs": ["{options.outputPath}"]
    }
  }
}
```

### Nx Caching

All executors support Nx caching for optimal performance:

```json
{
  "targets": {
    "build": {
      "cache": true,
      "dependsOn": ["^build"]
    }
  }
}
```

## Documentation

- 📚 **[Testing Guide](./docs/testing.md)** - Comprehensive testing documentation
- 🛠️ **[Configuration](./docs/configuration.md)** - Detailed configuration guide

## Requirements

- Node.js 18+
- Nx 18+
- Astro 4+

## Troubleshooting

### Astro not found

If you see `Astro binary not found` errors:

```bash
# Install Astro in your project
npm install -D astro
# or
pnpm add -D astro
```

### Port already in use

If the default port (4321) is in use, specify a different one:

```bash
nx dev my-astro-app --port 3000
```

### TypeScript errors

Ensure your `tsconfig.json` extends the workspace base config:

```json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "astro"
  }
}
```

## Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

## License

MIT © [Ludena Studio](https://ludena.studio)

## Links

- [Astro Documentation](https://docs.astro.build)
- [Nx Documentation](https://nx.dev)
- [GitHub Repository](https://github.com/ludena/nx-extensions)
- [Issue Tracker](https://github.com/ludena/nx-extensions/issues)