@ludena-studio/nx-astro 1.0.0

package/docs/configuration.md

@@ -0,0 +1,528 @@
+# Configuration Guide
+
+## Overview
+
+This guide covers the complete configuration setup for the `@ludena-studio/nx-astro` plugin and how it integrates with your Nx monorepo.
+
+## Project Setup
+
+### Generated Project Structure
+
+When you generate a new Astro app, the following structure is created:
+
+```
+apps/my-astro-app/
+├── src/
+│   ├── pages/
+│   │   └── index.astro
+│   └── env.d.ts
+├── astro.config.mjs
+├── tsconfig.json
+├── project.json
+└── README.md
+```
+
+### project.json Configuration
+
+The generated `project.json` contains all Nx-specific configuration:
+
+```json
+{
+  "name": "my-astro-app",
+  "projectType": "application",
+  "sourceRoot": "apps/my-astro-app/src",
+  "targets": {
+    "dev": {
+      "executor": "@ludena-studio/nx-astro:dev",
+      "options": {}
+    },
+    "serve": {
+      "executor": "@ludena-studio/nx-astro:dev",
+      "options": {}
+    },
+    "build": {
+      "executor": "@ludena-studio/nx-astro:build",
+      "options": {
+        "outputPath": "dist/apps/my-astro-app"
+      },
+      "outputs": ["{options.outputPath}"]
+    },
+    "preview": {
+      "executor": "@ludena-studio/nx-astro:preview",
+      "options": {},
+      "dependsOn": ["build"]
+    },
+    "add": {
+      "executor": "@ludena-studio/nx-astro:add",
+      "options": {}
+    }
+  },
+  "tags": []
+}
+```
+
+## Executor Configuration
+
+### Dev Executor
+
+Development server configuration:
+
+```json
+{
+  "targets": {
+    "dev": {
+      "executor": "@ludena-studio/nx-astro:dev",
+      "options": {
+        "port": 4321,
+        "host": false,
+        "open": false
+      }
+    }
+  }
+}
+```
+
+**Available Options:**
+- `port` (number) - Port number for dev server (default: 4321)
+- `host` (string | boolean) - Hostname or `true` for 0.0.0.0
+- `open` (boolean | string) - Open browser automatically, or specify URL path
+
+**Examples:**
+
+```bash
+# Use default port
+nx dev my-astro-app
+
+# Custom port
+nx dev my-astro-app --port 3000
+
+# Listen on all network interfaces
+nx dev my-astro-app --host
+
+# Open browser on start
+nx dev my-astro-app --open
+
+# Open specific path
+nx dev my-astro-app --open /about
+```
+
+### Build Executor
+
+Production build configuration:
+
+```json
+{
+  "targets": {
+    "build": {
+      "executor": "@ludena-studio/nx-astro:build",
+      "options": {
+        "outputPath": "dist/apps/my-astro-app"
+      },
+      "outputs": ["{options.outputPath}"],
+      "cache": true,
+      "dependsOn": ["^build"]
+    }
+  }
+}
+```
+
+**Available Options:**
+- `outputPath` (string) - Output directory for build artifacts
+
+**Caching:** Build results are cached by Nx for faster subsequent builds.
+
+### Preview Executor
+
+Preview server configuration:
+
+```json
+{
+  "targets": {
+    "preview": {
+      "executor": "@ludena-studio/nx-astro:preview",
+      "options": {
+        "port": 4321,
+        "host": false
+      },
+      "dependsOn": ["build"]
+    }
+  }
+}
+```
+
+**Available Options:**
+- `port` (number) - Port number for preview server
+- `host` (string | boolean) - Hostname or `true` for 0.0.0.0
+
+**Note:** Preview always depends on build target.
+
+### Add Executor
+
+Integration management configuration:
+
+```json
+{
+  "targets": {
+    "add": {
+      "executor": "@ludena-studio/nx-astro:add",
+      "options": {
+        "integration": "tailwind",
+        "yes": false
+      }
+    }
+  }
+}
+```
+
+**Available Options:**
+- `integration` (string, required) - Integration name
+- `yes` (boolean) - Skip confirmation prompts
+
+**Supported Integrations:**
+- `tailwind` - Tailwind CSS
+- `react` - React framework
+- `vue` - Vue framework
+- `svelte` - Svelte framework
+- `solid` - Solid.js framework
+- `mdx` - MDX support
+- `sitemap` - Sitemap generation
+- `partytown` - Partytown third-party scripts
+
+## TypeScript Configuration
+
+### tsconfig.json
+
+Generated TypeScript configuration:
+
+```json
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "astro",
+    "moduleResolution": "bundler",
+    "module": "ESNext",
+    "target": "ESNext",
+    "lib": ["ESNext", "DOM"],
+    "types": ["astro/client"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### Strict Mode
+
+Enable strict TypeScript checking:
+
+```bash
+nx g @ludena-studio/nx-astro:app my-app --strict
+```
+
+This adds:
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitAny": true
+  }
+}
+```
+
+## Astro Configuration
+
+### astro.config.mjs
+
+Basic Astro configuration:
+
+```javascript
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  // Configuration options
+});
+```
+
+### Adding Integrations
+
+Automatically via executor:
+```bash
+nx add my-astro-app --integration=tailwind
+```
+
+Manually in `astro.config.mjs`:
+```javascript
+import { defineConfig } from 'astro/config';
+import tailwind from '@astrojs/tailwind';
+
+export default defineConfig({
+  integrations: [tailwind()],
+});
+```
+
+### Output Options
+
+Configure output for different deployment targets:
+
+```javascript
+export default defineConfig({
+  output: 'static', // or 'server' or 'hybrid'
+  adapter: adapter(), // for server/hybrid
+});
+```
+
+## Workspace Integration
+
+### Nx Caching
+
+Enable caching for faster builds:
+
+```json
+{
+  "targets": {
+    "build": {
+      "cache": true,
+      "outputs": ["{options.outputPath}"]
+    }
+  }
+}
+```
+
+### Task Dependencies
+
+Configure task execution order:
+
+```json
+{
+  "targets": {
+    "build": {
+      "dependsOn": ["^build", "typecheck"]
+    },
+    "preview": {
+      "dependsOn": ["build"]
+    }
+  }
+}
+```
+
+### Tags and Constraints
+
+Organize projects with tags:
+
+```json
+{
+  "tags": ["scope:web", "type:app", "framework:astro"]
+}
+```
+
+Use in `nx.json` for constraints:
+
+```json
+{
+  "namedInputs": {
+    "default": ["{projectRoot}/**/*"],
+    "production": ["default", "!{projectRoot}/**/*.spec.ts"]
+  }
+}
+```
+
+## Environment Variables
+
+### Using .env Files
+
+Create `.env` file in project root:
+
+```bash
+# .env
+PUBLIC_API_URL=https://api.example.com
+SECRET_KEY=your-secret-key
+```
+
+Access in Astro:
+
+```astro
+---
+const apiUrl = import.meta.env.PUBLIC_API_URL;
+// Only PUBLIC_* vars are available client-side
+---
+```
+
+### Nx Integration
+
+Define in `project.json`:
+
+```json
+{
+  "targets": {
+    "build": {
+      "options": {
+        "env": {
+          "NODE_ENV": "production"
+        }
+      }
+    }
+  }
+}
+```
+
+## Advanced Configuration
+
+### Custom Scripts
+
+Add custom npm scripts in `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "nx dev my-astro-app",
+    "build": "nx build my-astro-app",
+    "preview": "nx preview my-astro-app"
+  }
+}
+```
+
+### Multiple Configurations
+
+Create configuration-specific targets:
+
+```json
+{
+  "targets": {
+    "build": {
+      "executor": "@ludena-studio/nx-astro:build",
+      "configurations": {
+        "production": {
+          "outputPath": "dist/apps/my-astro-app/production"
+        },
+        "staging": {
+          "outputPath": "dist/apps/my-astro-app/staging"
+        }
+      }
+    }
+  }
+}
+```
+
+Run with:
+```bash
+nx build my-astro-app --configuration=production
+```
+
+### Workspace Libraries
+
+Share code between apps using workspace libraries:
+
+```typescript
+// libs/shared/ui/src/index.ts
+export { Button } from './lib/button';
+
+// apps/my-astro-app/src/pages/index.astro
+---
+import { Button } from '@my-org/shared-ui';
+---
+```
+
+Configure path mapping in `tsconfig.base.json`:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@my-org/shared-ui": ["libs/shared/ui/src/index.ts"]
+    }
+  }
+}
+```
+
+## Migration Guide
+
+### From Standalone Astro
+
+1. **Move project to Nx workspace:**
+   ```bash
+   mv my-astro-project apps/
+   ```
+
+2. **Create project.json:**
+   ```bash
+   nx g @ludena-studio/nx-astro:app my-astro-project --skipInstall
+   ```
+
+3. **Update imports in `astro.config.mjs`** if using workspace libs
+
+4. **Update `tsconfig.json`** to extend workspace base config
+
+### From Other Framework
+
+Follow the Astro migration guide for your framework:
+- [React to Astro](https://docs.astro.build/en/guides/migrate-to-astro/from-create-react-app/)
+- [Vue to Astro](https://docs.astro.build/en/guides/migrate-to-astro/from-vue/)
+- [Next.js to Astro](https://docs.astro.build/en/guides/migrate-to-astro/from-nextjs/)
+
+## Troubleshooting
+
+### Build Output Location
+
+If build output is not where expected, verify `outputPath` in `project.json`:
+
+```json
+{
+  "targets": {
+    "build": {
+      "options": {
+        "outputPath": "dist/apps/my-astro-app"
+      },
+      "outputs": ["{options.outputPath}"]
+    }
+  }
+}
+```
+
+### Path Aliases Not Working
+
+Ensure `tsconfig.base.json` paths are correctly configured and `astro.config.mjs` includes:
+
+```javascript
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  vite: {
+    resolve: {
+      alias: {
+        '@my-org/shared': '/libs/shared/src',
+      },
+    },
+  },
+});
+```
+
+### Nx Cache Not Working
+
+Verify cache configuration:
+
+```json
+{
+  "targets": {
+    "build": {
+      "cache": true,
+      "outputs": ["{options.outputPath}"],
+      "inputs": [
+        "default",
+        "^production"
+      ]
+    }
+  }
+}
+```
+
+Clear cache if needed:
+```bash
+nx reset
+```
+
+## Resources
+
+- [Astro Configuration Reference](https://docs.astro.build/en/reference/configuration-reference/)
+- [Nx Project Configuration](https://nx.dev/reference/project-configuration)
+- [TypeScript Configuration](https://www.typescriptlang.org/tsconfig)