Skip to content

Latest commit

 

History

History
177 lines (146 loc) · 5.52 KB

README.md

File metadata and controls

177 lines (146 loc) · 5.52 KB

nx-simple:package

Compiles and packages TypeScript projects for publication to NPM, deployment as an app, or inclusion within another packagable project.

Features

  • Creates a publishable package to {workspaceRoot}/dist/{projectName}
  • Contains ESM and CJS builds
  • Generates a package.json with main, module, exports and dependencies fields
  • Copies README, LICENSE, and LICENCE files
  • Uses {projectRoot}.swcrc as base SWC config, if present
  • Generates SWC path mappings based on tsconfig baseUrl & paths
  • Type checks project using nearest tsconfig.json
  • Generates type definition (.d.ts) files
  • Detects and packages non-publishable dependencies into a local node_modules directory

Usage

project.json 
{
  "targets": {
    "package": {
      "executor": "nx-simple:package",
      "options": {
        "distribution": "npm",
        "targetRuntime": "es2018"
      }
    }
  }
}
project.json (unpublished sub-package) 
{
  "targets": {
    "package": {
      "executor": "nx-simple:package",
      "options": {
        "distribution": "lib",
        "targetRuntime": "es2018"
      }
    }
  }
}
tsconfig.json 
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": { "baseUrl": "src" } // 👈 tells nx-simple where source files are located
}
package.json 
{
  "type": "module",
  "exports": {
    "types": "src/index.ts", // 👈 entry point – removed by executor as adjacent .d.ts files are resolved automatically
    "import": "dist/index.js" // 👈 import path – used as base for `require` property to resolve CJS modules
  }
}
tsconfig.base.json 
// When analysing source files, Nx needs to be told how to resolve dependencies.
// Note: that these are only required to build the Nx graph.
// With NPM workspaces configured, packages are resolving via their npm link to node_modules.
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@scope/mylib/*": "packages/mylib/*"
    }
  }
}
nx.json 
{
  "tasksRunnerOptions": {
    "default": {
      "runner": "@nrwl/nx-cloud",
      "options": {
        "cacheableOperations": ["build", "package", "package:lib"]
      }
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*"]
  },
  "targetDefaults": {
    "nx-simple:package": {
      "inputs": ["default", "^default"],
      "outputs": [
        "{workspaceRoot}/dist/.nxsimple/{projectName}",
        "{workspaceRoot}/dist/{projectName}"
      ]
    },
    "package": {
      "dependsOn": ["^package:lib"]
    },
    "package:lib": {
      "dependsOn": ["^package:lib"]
    }
  }
}

Executor Options

Param Type Description Default
distribution "npm" creates a distribution that can be published to NPM required
distribution "app" creates a distribution that can be installed required
distribution "lib" creates a sub-package that can be copied to another distribution required
targetRuntime "es5" | "es6" | "esYYYY" the target JavaScript environment "es2020"

Notes:

  1. A package configured with "distribution": "npm" | "app" will include any non-publishable dependencies in its build.
  2. Publishable projects have one of the following in their project.json:
    1. the package executor, also configured with "distribution": "npm"
    2. a publish target, configured with any executor
    3. "willPublish": true set at the root level
  3. Non-publishable sub-package that are dependencies of publishable packages should have a package executor configured with "distribution": "lib"

Project Configuration

The executor also reads configuration from these files:

File Param Required Description
tsconfig.json compilerOptions.baseUrl yes the directory containing source code (within project directory)
.swcrc {} no swc configuration, which may be partially overwritten by the executor

Workspace Configuration

File Param Required Description
nx.json targetDefaults yes Inform Nx where the executor writes its artefacts. See nx.json example.