Getting Started & Installation

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• packages/docusaurus/README.md
• packages/github-pages/README.md
• packages/docusaurus/src/generators/application/generator.ts
• e2e/docusaurus-e2e/tests/docusaurus.test.ts
• packages/core/CHANGELOG.md

nx-extend consists of a collection of Nx plugins providing production-ready tools for cloud deployment, infrastructure management, testing frameworks, and localization. These plugins extend modern full-stack development workflows within an Nx workspace by providing specific executors and generators for platforms like Google Cloud, Vercel, Firebase, and GitHub Pages.
Sources: README.md:3-8

Installation and Quick Start

You manage nx-extend plugins through standard package managers and Nx CLI commands. The general workflow involves installing the specific plugin package, running an initialization generator to set up the project structure, and then executing targets defined in project.json.
Sources: README.md:104-114

Core Installation Steps

1. Install a specific plugin:
   Use your package manager to add the desired plugin to your dev dependencies.

   npm install -D @nx-extend/<plugin-name>
   

2. Initialize the plugin:
   If the plugin provides an initialization generator, execute it to configure your workspace.

   nx g @nx-extend/<plugin-name>:init
   

3. Execute targets:
   Run specific tasks such as building or deploying using the plugin's executors.

   nx <target> <project-name>
   

Sources: README.md:104-114

The following diagram illustrates the typical onboarding flow for a new plugin:

This flow represents the standard lifecycle from package acquisition to task execution.
Sources: README.md:104-114, packages/github-pages/README.md:28-48

Plugin Management and Support

Compatibility Requirements

nx-extend maintains strict version alignment with the Nx ecosystem. Current releases require @nx/devkit version ^21.0.0 or ^22.0.0 depending on the specific package version.
Sources: packages/core/CHANGELOG.md:22-35, packages/core/CHANGELOG.md:11-20

Key Categories of Plugins

Category	Available Plugins	Installation Example
Cloud Deployment	GCP Cloud Run, GCP Functions, Firebase, Vercel	npm install -D @nx-extend/vercel
Infrastructure	Terraform, Pulumi	npm install -D @nx-extend/terraform
Testing	E2E Runner, Playwright (deprecated)	npm install -D @nx-extend/e2e-runner
UI & CMS	Shadcn-ui, Strapi, Docusaurus	npm install -D @nx-extend/docusaurus
CI/CD Actions	set-shas, plan, run-many	uses: tripss/nx-extend/actions/plan@master
Sources: README.md:13-91

Specific Plugin Setup Examples

Docusaurus Integration

The Docusaurus plugin automates the creation of documentation sites within the Nx workspace. It configures a development server with hot reload and production build optimization.
Sources: packages/docusaurus/README.md:8-14

Generator Process:

1. Normalization: The generator computes the project root (defaulting to apps/) and formats tags.
2. Configuration: It adds a project configuration to the workspace with build and serve targets.
3. File Generation: It creates project files from templates and updates workspace-level ignores (.gitignore and .prettierignore).
4. Dependencies: It automatically adds core Docusaurus packages including @docusaurus/core, react, and typescript.
   Sources: packages/docusaurus/src/generators/application/generator.ts:24-124

The sequence diagram shows how the generator coordinates file creation and workspace updates.
Sources: packages/docusaurus/src/generators/application/generator.ts:100-142, e2e/docusaurus-e2e/tests/docusaurus.test.ts:12-16

GitHub Pages Deployment

Deployment to GitHub Pages requires the @nx-extend/github-pages plugin and specific environment variables for authentication.
Sources: packages/github-pages/README.md:18-24

Requirements:

• A GitHub repository with Pages enabled.
• GH_PAGES_ACCESS_TOKEN environment variable containing a Personal Access Token with write permissions.
• A pre-configured build target in project.json that the deploy executor can reference via outputPath.
  Sources: packages/github-pages/README.md:18-59

Summary

To get started with nx-extend, you install the specific plugin matching your target platform and run its associated initialization generator. The system integrates directly with Nx's task running architecture, allowing you to build, test, and deploy using standard nx <target> commands while the plugins handle environment variables and platform-specific CLI toolings.
Sources: README.md:104-114, packages/github-pages/README.md:26-30