Nx plugin

npx frontmcp create help-desk-platform --nx      # a new workspace
npx nx add @frontmcp/nx@1.9.3                     # or, in a workspace you have
npx nx g @frontmcp/nx:app tickets
npx nx dev tickets

Reference

What it adds

$ npx nx list @frontmcp/nx
 NX   Capabilities in @frontmcp/nx:

GENERATORS
init : Prepare an existing Nx workspace for FrontMCP (dependencies and cacheable executors)
workspace : Scaffold a full FrontMCP Nx monorepo with apps/, libs/, and servers/ directories
app : Generate a FrontMCP application in apps/
lib : Generate a shared library in libs/
server : Generate a deployment shell in servers/
tool : Generate a @Tool class
…
EXECUTORS/BUILDERS
build : Compile a FrontMCP project using frontmcp build
build-exec : Build a distributable bundle using frontmcp build --target node
dev : Start a development server using frontmcp dev
serve : Start a supervised production server using frontmcp start
test : Run E2E tests using frontmcp test
inspector : Launch MCP Inspector using frontmcp inspector
deploy : Deploy to a target platform (node/vercel/lambda/cloudflare)

No generator adds your class to its app: after nx g @frontmcp/nx:tool, list the tool in the app's @App({ tools }) yourself.

Installing it

Either let frontmcp create make the workspace, or add the plugin to a workspace you have.

frontmcp create <name> --nx

1. Writes <name>/package.json with the Nx tooling and @frontmcp/nx, and installs them.
2. Runs the plugin's workspace generator with a sample demo app.
3. Installs the dependencies the generator wrote, and commits everything as Initial commit.

--pm yarn or --pm pnpm uses that package manager; create's other flags are ignored. All three installs finish, and the demo app builds, type-checks and passes its test with each. With npm, step 3 failed with ERESOLVE on @swc/core before 1.8.7; the workspace pins @swc/core ~1.15.8.

nx add @frontmcp/nx in an existing workspace

npx nx add @frontmcp/nx@1.9.3

Installing @frontmcp/nx@1.9.3...
Initializing @frontmcp/nx...

 NX  Generating @frontmcp/nx:init

UPDATE nx.json
UPDATE package.json
…
 NX   Package @frontmcp/nx added successfully.

nx add runs the plugin's init generator, which does two things:

• package.json: adds @frontmcp/sdk, frontmcp, reflect-metadata, zod and tslib to dependencies, and @frontmcp/nx, @frontmcp/testing, jest, @swc/jest and @types/jest to devDependencies, then installs. A version you already have stays.
• nx.json: adds targetDefaults for @frontmcp/nx:build and @frontmcp/nx:build-exec with cache: true and dependsOn: ["^build"] (and inputs: ["production", "^production"] when the workspace defines production), and for @frontmcp/nx:test with cache: true and Nx's default inputs. So those targets are cached whatever their project.json says, and changing a test file runs the tests again.

Before 1.8.7 the plugin had no init: nx add changed nothing but devDependencies, and you installed FrontMCP yourself. If you added the package with npm install instead of nx add, run npx nx g @frontmcp/nx:init. It changes nothing the second time, and keeps targetDefaults you already have.

Workspace layout

The generators and executors assume this layout, which the workspace generator writes:

Every executor runs the CLI from the project's folder, with absolute paths as options (--entry /Users/you/help-desk-platform/apps/tickets/src/main.ts). So the CLI reads the project's own package.json, tsconfig.json, .env and frontmcp.config.*, and a bundle is named after the project (tickets.bundle.js). Executors has the details.

Each generated tsconfig.json sets what a FrontMCP project needs whatever the base config says: module commonjs, moduleResolution bundler on TypeScript 6 and later (node10 on TypeScript 5), rootDir at the workspace root, composite, declarationMap and emitDeclarationOnly false, decorators on, and "nx": { "addTypecheckTarget": false }, so Nx's TypeScript plugin, where there is one, doesn't add a typecheck of its own.

What frontmcp create --nx writes

Since 1.9, nx.json has no @nx/js/typescript plugin. That plugin inferred a build and a typecheck for every project: the typecheck failed with TS5069, and the build it gave each library needed a root tsconfig.json. Projects now carry their own typecheck target instead, and a library needs no build of its own, since the app's bundle compiles it in.

Upgrading a 1.8.7 workspace

The generators of 1.9.2 assume a workspace without @nx/js/typescript, and they never edit a project's files, only add new ones. In a workspace made by frontmcp create --nx at 1.8.7:

• Remove the @nx/js/typescript entry from plugins in nx.json. While it's there, a library made by lib keeps an inferred build, and nx build of an app that imports the library stops with [@nx/js:typescript-sync]: Missing root "tsconfig.json".
• In a workspace where you ran nx add @frontmcp/nx at 1.8.7, delete the inputs line from targetDefaults["@frontmcp/nx:test"], if there is one. It was ["production", "^production"], which leaves test files out, so a changed test could be answered from the cache.

Projects generated with 1.8.7 keep their project.json and tsconfig files. Compare them with a project you generate with 1.9.2 to pick up its typecheck target and tsconfig.json settings.

Usage

Creating a workspace

npx frontmcp create help-desk-platform --nx
cd help-desk-platform
npx nx show projects
npx nx dev demo

["demo"]

> nx run demo:dev
Running: frontmcp dev --entry /Users/you/help-desk-platform/apps/demo/src/main.ts (in /Users/you/help-desk-platform/apps/demo)
[dev] using entry: src/main.ts
[dev] listening on port: 3000
[dev] starting tsx --watch and tsc --noEmit --watch (async type-checker)
…
MCP HTTP (Express) on 127.0.0.1:3000
[10:31:39 PM] Found 0 errors. Watching for file changes.

The demo server answers at http://localhost:3000/, at the root. To serve it at /mcp and pick the port, put a frontmcp.config.ts in apps/demo/: the executors run the CLI there, so it reads that file (Executors).

import { defineConfig } from "frontmcp";

export default defineConfig({
  name: "demo",
  deployments: [{ target: "node" }],
  transport: { default: "http", http: { port: 4100, path: "/mcp" } },
});

nx test demo runs the app's test, nx typecheck demo checks the app and its tests, and nx build demo writes apps/demo/dist/node/demo.bundle.js.

Adding the plugin to a workspace you have

In a workspace made with create-nx-workspace (--preset=ts, which made Nx 23.2.0 with TypeScript 6.0.3):

npx nx add @frontmcp/nx@1.9.3
npx nx g @frontmcp/nx:app support
npx nx run-many -t build typecheck test -p support
npx nx dev support

 NX  Generating @frontmcp/nx:app

CREATE apps/support/jest.config.cjs
CREATE apps/support/package.json
CREATE apps/support/project.json
CREATE apps/support/src/support.app.ts
CREATE apps/support/src/main.ts
CREATE apps/support/src/tools/hello.tool.spec.ts
CREATE apps/support/src/tools/hello.tool.ts
CREATE apps/support/tsconfig.json
CREATE apps/support/tsconfig.lib.json
CREATE apps/support/tsconfig.spec.json
…
 NX   Successfully ran targets build, typecheck, test for project support

That workspace's tsconfig.base.json is a TypeScript-solution one (composite, emitDeclarationOnly, declarationMap, customConditions, module nodenext), and the app's tsconfig.json overrides what a FrontMCP app can't use:

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "module": "commonjs",
    "moduleResolution": "bundler",
    "rootDir": "../../",
    "composite": false,
    "declarationMap": false,
    "emitDeclarationOnly": false
  }
}

(Only the options that matter are shown.) nx dev support's type checker reports Found 0 errors. A library from the lib generator works there too: its alias takes the workspace's npm scope, from the root package.json's @org/source, and is written "@org/util": ["./libs/util/src/index.ts"], with the ./ TypeScript needs when the base config has no baseUrl. That workspace keeps its @nx/js/typescript plugin, so the library also gets an inferred build (tsc --build tsconfig.lib.json), which works because the preset made a root tsconfig.json. Once the app imports the library, nx build support stops with The workspace is out of sync until you run npx nx sync, which adds the project references to the root tsconfig.json; then it runs the library's build first (Running target build for project support and 1 task it depends on). The UI generators work there too (UI generators). In 1.8.7 the app's tsconfig.json needed these overrides by hand (TS5098, then no JavaScript emitted), and the alias needed its ./ (TS5090).

Seeing what an app runs

An app's targets are the ones its generator wrote in project.json:

{
  "name": "tickets",
  "sourceRoot": "apps/tickets/src",
  "projectType": "application",
  "tags": ["scope:apps"],
  "targets": {
    "build": {
      "executor": "@frontmcp/nx:build",
      "cache": true,
      "outputs": ["{projectRoot}/dist"],
      "options": { "entry": "{projectRoot}/src/main.ts", "outputPath": "{projectRoot}/dist" }
    },
    "dev": { "executor": "@frontmcp/nx:dev", "options": { "entry": "{projectRoot}/src/main.ts" } },
    "serve": { "executor": "@frontmcp/nx:serve", "options": { "entry": "{projectRoot}/src/main.ts" } },
    "test": { "executor": "@frontmcp/nx:test", "cache": true, "options": {} },
    "typecheck": {
      "executor": "nx:run-commands",
      "cache": true,
      "options": {
        "commands": ["tsc --noEmit -p tsconfig.lib.json", "tsc --noEmit -p tsconfig.spec.json"],
        "parallel": false,
        "cwd": "{projectRoot}"
      }
    },
    "inspector": { "executor": "@frontmcp/nx:inspector", "options": {} }
  }
}

npx nx show project tickets --json shows them as Nx runs them: build also gets dependsOn: ["^build"] and the production inputs from nx.json's targetDefaults. typecheck checks the app's code with tsconfig.lib.json and its tests with tsconfig.spec.json.

Troubleshooting

The "frontmcp" CLI is not installed in …

An executor found no node_modules/frontmcp in the workspace root, and doesn't download one. Run npx nx g @frontmcp/nx:init, or npm install --save-dev frontmcp at the version of your @frontmcp/sdk.

Cannot find module '@frontmcp/sdk'

The workspace doesn't have FrontMCP installed. nx add @frontmcp/nx and nx g @frontmcp/nx:init install it; if you ran init with --skipPackageJson or added the plugin with npm install, run init without it.

error TS5098: Option 'customConditions' can only be used when 'moduleResolution' is set to …

An app generated before 1.9, in a workspace whose tsconfig.base.json is a TypeScript-solution one. Give its tsconfig.json the compilerOptions the 1.9.2 generator writes: Adding the plugin to a workspace you have.

error TS5069: Option 'emitDeclarationOnly' cannot be specified without specifying option 'declaration' or option 'composite'

From nx typecheck on a project generated before 1.9, which has no typecheck target of its own, so Nx's TypeScript plugin infers one that can't work with that project's tsconfig.json. Add the typecheck target a 1.9.2 project has (Seeing what an app runs), or check types with npx tsc -p apps/<app>/tsconfig.lib.json --noEmit.

The workspace is probably out of sync because a sync generator failed to run

With [@nx/js:typescript-sync]: Missing root "tsconfig.json". nx.json still lists @nx/js/typescript, as a workspace made with 1.8.7 does, which gives each library an inferred build that needs a root tsconfig.json. Remove the plugin from nx.json (Upgrading a 1.8.7 workspace), or add a root tsconfig.json: Monorepo patterns.