@clipboard-health/nx-plugin 0.0.0

package/.eslintrc.json

@@ -0,0 +1,32 @@
+{
+  "extends": ["../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.json"],
+      "parser": "jsonc-eslint-parser",
+      "rules": {
+        "@nx/dependency-checks": "error"
+      }
+    },
+    {
+      "files": ["./package.json", "./generators.json"],
+      "parser": "jsonc-eslint-parser",
+      "rules": {
+        "@nx/nx-plugin-checks": "error"
+      }
+    }
+  ]
+}

package/README.md

@@ -0,0 +1,50 @@
+# @clipboard-health/nx-plugin
+
+Clipboard Health's Nx plugin contains generators to manage libraries within an Nx workspace.
+
+## Table of Contents
+
+- [Table of Contents](#table-of-contents)
+- [Install](#install)
+- [Usage](#usage)
+  - [Adding new libraries](#adding-new-libraries)
+  - [Porting existing libraries](#porting-existing-libraries)
+
+## Install
+
+```bash
+npm install @clipboard-health/nx-plugin
+```
+
+## Usage
+
+### Adding new libraries
+
+Libraries version and publish separately. We use [Nx Local Generators](https://nx.dev/recipes/generators/local-generators) to generate library stubs that successfully build, lint, and test. The `--publishable` flag sets up semantic versioning from commit messages, GitHub Release creation, and NPM publishing on merges to `main` (but only if the code within your library package changed, thanks to Nx's dependency graph).
+
+```bash
+# Optionally, include the --publishable flag to publish to NPM.
+npx nx generate @clipboard-health/nx-plugin:node-lib [PROJECT_NAME]
+
+# Change your mind? Remove it just as easily...
+npx nx generate @nx/workspace:remove --projectName [PROJECT_NAME]
+
+# ...or rename it. Note: after running this command, perform a find/replace for remaining references
+# to the old name.
+npx nx generate @nx/workspace:move --projectName [PROJECT_NAME] --destination [NEW_PROJECT_NAME]
+```
+
+### Porting existing libraries
+
+Follow [Adding new libraries](#adding-new-libraries) to generate a new package and copy the code from the existing library into it.
+
+To keep the same project name while avoiding publishing version conflicts, create a `git tag` from the last commit on `main` with the project name and version:
+
+```bash
+git checkout main
+
+# Where [VERSION] is the current version of the project
+git tag --annotate [PROJECT_NAME]-[VERSION] --message "Port from [OLD_LOCATION]"
+
+git push origin [PROJECT_NAME]-[VERSION]
+```

package/generators.json

@@ -0,0 +1,9 @@
+{
+  "generators": {
+    "node-lib": {
+      "factory": "./src/generators/node-lib/generator",
+      "schema": "./src/generators/node-lib/schema.json",
+      "description": "Create a Node.js library."
+    }
+  }
+}

package/jest.config.ts

@@ -0,0 +1,20 @@
+/* eslint-disable */
+export default {
+  coverageDirectory: "../../coverage/packages/nx-plugin",
+  coveragePathIgnorePatterns: [],
+  coverageThreshold: {
+    global: {
+      branches: 80,
+      functions: 100,
+      lines: 95,
+      statements: 95,
+    },
+  },
+  displayName: "nx-plugin",
+  moduleFileExtensions: ["ts", "js"],
+  preset: "../../jest.preset.js",
+  testEnvironment: "node",
+  transform: {
+    "^.+\\.[tj]s$": ["ts-jest", { tsconfig: "<rootDir>/tsconfig.spec.json" }],
+  },
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@clipboard-health/nx-plugin",
+  "description": "Clipboard Health's Nx plugin contains generators to manage applications within an Nx workspace.",
+  "version": "0.0.0",
+  "bugs": "https://github.com/clipboardhealth/core-utils/issues",
+  "dependencies": {
+    "@nx/devkit": "19.5.6",
+    "@nx/js": "19.5.6",
+    "tslib": "2.6.3"
+  },
+  "generators": "./generators.json",
+  "keywords": [
+    "Generator",
+    "Library",
+    "Node",
+    "Nx",
+    "Plugin",
+    "TypeScript"
+  ],
+  "license": "MIT",
+  "main": "./src/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clipboardhealth/core-utils.git",
+    "directory": "packages/nx-plugin"
+  },
+  "type": "commonjs",
+  "typings": "./src/index.d.ts"
+}

package/project.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "name": "nx-plugin",
+  "projectType": "library",
+  "sourceRoot": "packages/nx-plugin/src",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "options": {
+        "assets": [
+          "packages/nx-plugin/*.md",
+          {
+            "input": "./packages/nx-plugin/src",
+            "glob": "**/!(*.ts)",
+            "output": "./src"
+          },
+          {
+            "input": "./packages/nx-plugin/src",
+            "glob": "**/*.d.ts",
+            "output": "./src"
+          },
+          {
+            "input": "./packages/nx-plugin",
+            "glob": "generators.json",
+            "output": "."
+          }
+        ],
+        "main": "packages/nx-plugin/src/index.ts",
+        "outputPath": "dist/packages/nx-plugin",
+        "tsConfig": "packages/nx-plugin/tsconfig.lib.json"
+      },
+      "outputs": ["{options.outputPath}"]
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "options": {
+        "maxWarnings": 0
+      }
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "options": {
+        "jestConfig": "packages/nx-plugin/jest.config.ts",
+        "passWithNoTests": false
+      },
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"]
+    }
+  }
+}

package/src/generators/node-lib/files/.eslintrc.json__template__

@@ -0,0 +1,8 @@
+{
+  "extends": ["<%= offsetFromRoot %>.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "parserOptions": {
+    "project": "tsconfig.lint.json",
+    "tsconfigRootDir": "packages/<%= projectName %>"
+  }
+}

package/src/generators/node-lib/files/README.md__template__

@@ -0,0 +1,21 @@
+# <%= importPath %>
+
+TODO
+
+## Table of Contents
+
+- [Install](#install)
+- [Usage](#usage)
+- [Local development commands](#local-development-commands)
+
+## Install
+
+```bash
+npm install <%= importPath %>
+```
+
+## Usage
+
+## Local development commands
+
+See [`package.json`](./package.json) `scripts` for a list of commands.

package/src/generators/node-lib/files/jest.config.ts__template__

@@ -0,0 +1,19 @@
+export default {
+  coverageDirectory: "../../coverage/packages/<%= projectName %>",
+  coveragePathIgnorePatterns: [],
+  coverageThreshold: {
+    global: {
+      branches: 100,
+      functions: 100,
+      lines: 100,
+      statements: 100,
+    },
+  },
+  displayName: "<%= projectName %>",
+  moduleFileExtensions: ["ts", "js"],
+  preset: "<%= offsetFromRoot %>jest.preset.js",
+  testEnvironment: "node",
+  transform: {
+    "^.+\\.[tj]s$": ["ts-jest", { tsconfig: "<rootDir>/tsconfig.spec.json" }],
+  },
+};

package/src/generators/node-lib/files/package.json__template__

@@ -0,0 +1,10 @@
+{
+  "name": "<%= importPath %>",
+  "version": "0.0.1",
+  "dependencies": {
+    "tslib": "2.6.3"
+  },
+  "main": "./src/index.js",
+  "type": "commonjs",
+  "typings": "./src/index.d.ts"
+}

package/src/generators/node-lib/files/project.json__template__

@@ -0,0 +1,46 @@
+{
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "name": "<%= projectName %>",
+  "projectType": "library",
+  "sourceRoot": "packages/<%= projectName %>/src",<% if (publishable) { %>
+  "release": {
+    "version": {
+      "generatorOptions": {
+        "packageRoot": "dist/{projectRoot}",
+        "currentVersionResolver": "git-tag"
+      }
+    }
+  },<% } %>
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "options": {
+        "assets": ["packages/<%= projectName %>/*.md"],
+        "main": "packages/<%= projectName %>/src/index.js",
+        "outputPath": "dist/packages/<%= projectName %>",
+        "tsConfig": "packages/<%= projectName %>/tsconfig.lib.json"
+      },
+      "outputs": ["{options.outputPath}"]
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "options": {
+        "lintFilePatterns": ["packages/<%= projectName %>/**/*.[jt]s"],
+        "maxWarnings": 0
+      },
+      "outputs": ["{options.outputFile}"]
+    },<% if (publishable) { %>
+    "nx-release-publish": {
+      "options": {
+        "packageRoot": "dist/{projectRoot}"
+      }
+    },<% } %>
+    "test": {
+      "executor": "@nx/jest:jest",
+      "options": {
+        "jestConfig": "packages/<%= projectName %>/jest.config.ts"
+      }
+    }
+  }
+}

package/src/generators/node-lib/files/src/index.ts

@@ -0,0 +1 @@
+export * from "./lib/rename-me";

package/src/generators/node-lib/files/src/lib/rename-me.spec.ts

@@ -0,0 +1,7 @@
+import { deleteMe } from "./rename-me";
+
+describe("deleteMe", () => {
+  it("works", () => {
+    expect(deleteMe()).toBe("hello");
+  });
+});

package/src/generators/node-lib/files/src/lib/rename-me.ts

@@ -0,0 +1,3 @@
+export function deleteMe(): string {
+  return "hello";
+}

package/src/generators/node-lib/files/tsconfig.json__template__

@@ -0,0 +1,19 @@
+{
+  "extends": "<%= offsetFromRoot %>tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc"
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.lint.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

package/src/generators/node-lib/files/tsconfig.lib.json__template__

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["jest.config.ts", "src/**/*.spec.ts", "src/**/*.test.ts"]
+}

package/src/generators/node-lib/files/tsconfig.lint.json__template__

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": ["jest", "node"]
+  },
+  "include": ["."]
+}

package/src/generators/node-lib/files/tsconfig.spec.json__template__

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": ["jest", "node"]
+  },
+  "include": ["jest.config.ts", "src/**/*.test.ts", "src/**/*.spec.ts", "src/**/*.d.ts"]
+}

package/src/generators/node-lib/files/typedoc.json__template__

@@ -0,0 +1,4 @@
+{
+  "extends": ["../../typedoc.base.json"],
+  "entryPoints": ["src/index.ts"]
+}

package/src/generators/node-lib/generator.spec.ts

@@ -0,0 +1,19 @@
+import { readProjectConfiguration, type Tree } from "@nx/devkit";
+import { createTreeWithEmptyWorkspace } from "@nx/devkit/testing";
+
+import generator from "./generator";
+
+describe("generator", () => {
+  let appTree: Tree;
+
+  beforeEach(() => {
+    appTree = createTreeWithEmptyWorkspace({ layout: "apps-libs" });
+  });
+
+  it("runs successfully", async () => {
+    const name = "test";
+    await generator(appTree, { name });
+    const config = readProjectConfiguration(appTree, name);
+    expect(config).toBeDefined();
+  });
+});

package/src/generators/node-lib/generator.ts

@@ -0,0 +1,85 @@
+import { join } from "node:path";
+
+import {
+  formatFiles,
+  generateFiles,
+  getWorkspaceLayout,
+  joinPathFragments,
+  names,
+  offsetFromRoot,
+  type Tree,
+  updateJson,
+} from "@nx/devkit";
+import { getImportPath } from "@nx/js/src/utils/get-import-path";
+
+import type { NxPluginGeneratorSchema } from "./schema";
+
+const ROOT_TS_CONFIG = "tsconfig.base.json";
+
+type NormalizedSchema = NxPluginGeneratorSchema & {
+  importPath: string;
+  projectName: string;
+  projectRoot: string;
+  projectDirectory: string;
+};
+
+function normalizeOptions(tree: Tree, options: NxPluginGeneratorSchema): NormalizedSchema {
+  const name = names(options.name).fileName;
+  const projectDirectory = name;
+  return {
+    ...options,
+    publishable: options.publishable ?? false,
+    importPath: getImportPath(tree, projectDirectory),
+    projectName: name.replaceAll("/", "-"),
+    projectRoot: `${getWorkspaceLayout(tree).libsDir}/${name}`,
+    projectDirectory,
+  };
+}
+
+function getRelativePathToRootTsConfig(targetPath: string): string {
+  return `${offsetFromRoot(targetPath)}${ROOT_TS_CONFIG}`;
+}
+
+function addFiles(tree: Tree, options: NormalizedSchema) {
+  generateFiles(tree, join(__dirname, "files"), options.projectRoot, {
+    ...options,
+    ...names(options.name),
+    offsetFromRoot: offsetFromRoot(options.projectRoot),
+    rootTsConfigPath: getRelativePathToRootTsConfig(options.projectRoot),
+    template: "",
+  });
+}
+
+function updateRootTsConfig(
+  host: Tree,
+  options: {
+    name: string;
+    importPath: string;
+    projectRoot: string;
+  },
+) {
+  updateJson<{ compilerOptions: { paths: Record<string, string[]> } }>(
+    host,
+    ROOT_TS_CONFIG,
+    (json) => {
+      const c = json.compilerOptions;
+      c.paths ||= {};
+      delete c.paths[options.name];
+
+      if (c.paths[options.importPath]) {
+        throw new Error(`There is already a library with import path "${options.importPath}".`);
+      }
+
+      c.paths[options.importPath] = [joinPathFragments(options.projectRoot, "./src", "index.ts")];
+
+      return json;
+    },
+  );
+}
+
+export default async function generate(tree: Tree, options: NxPluginGeneratorSchema) {
+  const normalizedOptions = normalizeOptions(tree, options);
+  addFiles(tree, normalizedOptions);
+  updateRootTsConfig(tree, normalizedOptions);
+  await formatFiles(tree);
+}

package/src/generators/node-lib/schema.d.ts

@@ -0,0 +1,4 @@
+export interface NxPluginGeneratorSchema {
+  name: string;
+  publishable?: boolean;
+}

package/src/generators/node-lib/schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "NodeLib",
+  "title": "Create a Node.js library.",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Library name.",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "Library name?",
+      "pattern": "(?:^@[a-zA-Z0-9-*~][a-zA-Z0-9-*._~]*\\/[a-zA-Z0-9-~][a-zA-Z0-9-._~]*|^[a-zA-Z][^:]*)$"
+    },
+    "publishable": {
+      "type": "boolean",
+      "default": false,
+      "description": "Create a publishable library.",
+      "x-priority": "important"
+    }
+  },
+  "required": ["name"]
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "outDir": "../../dist/out-tsc"
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

package/tsconfig.lib.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["jest.config.ts", "src/**/*.spec.ts", "src/**/*.test.ts"]
+}

package/tsconfig.spec.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": ["jest", "node"]
+  },
+  "include": ["jest.config.ts", "src/**/*.test.ts", "src/**/*.spec.ts", "src/**/*.d.ts"]
+}

package/typedoc.json

@@ -0,0 +1,4 @@
+{
+  "extends": ["../../typedoc.base.json"],
+  "entryPoints": ["src/index.ts"]
+}