TypeScript Projects

The TypeScript project generator can be used to create a modern TypeScript library or application configured with best practices such as ECMAScript Modules (ESM), TypeScript project references, Vitest for running tests and Biome for linting and formatting.

Usage

Generate a TypeScript Project

You can generate a new TypeScript project in two ways:

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - ts#project
5. Fill in the required parameters
6. Click Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#project

yarn

yarn nx g @aws/nx-plugin:ts#project

npm

npx nx g @aws/nx-plugin:ts#project

bun

bunx nx g @aws/nx-plugin:ts#project

You can also perform a dry-run to see what files would be changed

pnpm

pnpm nx g @aws/nx-plugin:ts#project --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#project --dry-run

npm

npx nx g @aws/nx-plugin:ts#project --dry-run

bun

bunx nx g @aws/nx-plugin:ts#project --dry-run

Options

Parameter	Type	Default	Description
name Required	string	-	TypeScript project name
directory	string	packages	Parent directory where the library is placed.
subDirectory	string	-	The sub directory the lib is placed in. By default this is the library name.
preferInstallDependencies	boolean	true	Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

Generator Output

The generator will create the following project structure in the <directory>/<name> directory:

• Directorysrc TypeScript source code

  • index.ts
• package.json Project manifest defining the project’s package name and dependencies
• project.json Project configuration and build targets
• tsconfig.json Base TypeScript configuration for this project (extends workspace root tsconfig.base.json)
• tsconfig.lib.json TypeScript configuration for your library (your runtime or packaged source)
• tsconfig.spec.json TypeScript configuration for your tests
• vitest.config.mts Configuration for Vitest

Project package.json

The project’s package.json starts minimal. As you add runtime dependencies they are declared here (shared build/test tooling stays in the workspace root) — you can find out more below.

You will also notice some changes to the following files in your workspace root:

• nx.json Nx configuration is updated to configure the @nx/js/typescript plugin for your project
• tsconfig.base.json a TypeScript alias is set up for your project so that it can be imported by other projects in your workspace
• tsconfig.json a TypeScript project reference is added for your project

Writing TypeScript Source Code

Add your TypeScript code in the src directory.

ESM Import Syntax

Since your TypeScript project is an ES Module, be sure to write your import statements with the correct ESM syntax, explicitly referencing the file extension:

index.ts

import { sayHello } from './hello.js';

TypeScript References

Even though we’re using TypeScript, and sayHello is defined in hello.ts, we use the .js file extension in our import. You can read more about this here.

Exporting for Other TypeScript Projects

The entry point for your TypeScript project is src/index.ts. You can add exports here for anything you’d like other projects to be able to import:

src/index.ts

export { sayHello } from './hello.js';
export * from './algorithms/index.js';

Importing your Library Code in Other Projects

TypeScript aliases for your project are configured in your workspace tsconfig.base.json, which allows you to reference your TypeScript project from other TypeScript projects:

packages/my-other-project/src/index.ts

import { sayHello } from '@my-scope/my-library';

When you add an import statement for a new project in your workspace for the first time, you will likely see an error in your IDE similar to the below:

Import error

File '/path/to/my/workspace/packages/my-library/src/index.ts' is not under 'rootDir' '/path/to/my/workspace/packages/my-consumer'. 'rootDir' is expected to contain all source files.
  File is ECMAScript module because '/path/to/my/workspace/package.json' has field "type" with value "module" ts(6059)
File '/path/to/my/workspace/packages/my-library/src/index.ts' is not listed within the file list of project '/path/to/my/workspace/packages/my-consumer/tsconfig.lib.json'. Projects must list all files or use an 'include' pattern.
  File is ECMAScript module because '/path/to/my/workspace/package.json' has field "type" with value "module" ts(6307)

This is because a project reference has not yet been set up, and the imported project has not yet been declared as a workspace dependency in your project’s package.json.

Your workspace is configured with sync generators which manage both for you, so you don’t need to configure them by hand. Simply run the following command and Nx will add the required configuration:

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

 NX   The workspace is out of sync

[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on, contain stale project references, or have duplicate project references.
[@aws/nx-plugin:ts#sync]: Local project dependencies are out of sync. The following workspace dependencies will be declared:
packages/my-other-project/package.json:
- @my-scope/my-library: workspace:*

Syncing the workspace...
The workspace was synced successfully!

Nx’s TypeScript sync generator adds the project reference, and the plugin’s ts#sync generator declares the imported project in your project’s package.json (workspace:* where the package manager supports the workspace protocol, * on npm and yarn classic), so the package manager links the local project on install. After this, the error in your IDE should be gone and you are ready to use your library.

Build Shortcut

You can also just build your project — the sync generators run first and you’ll be prompted to apply any outstanding changes:

 NX   The workspace is out of sync

...

? Would you like to sync the identified changes to get your workspace up to date? …
Yes, sync the changes and run the tasks
No, run the tasks without syncing the changes

Select Yes to allow Nx to sync your workspace.

Keeping Path Aliases In Sync

If you add custom compilerOptions.paths entries in a project’s tsconfig.json, TypeScript stops inheriting the workspace aliases defined in tsconfig.base.json. The hidden ts#sync generator runs before the compile target (configured in nx.json) to copy any missing base aliases into tsconfig.json, tsconfig.lib.json and tsconfig.app.json files that already declare paths. To opt out, remove @aws/nx-plugin:ts#sync from targetDefaults.compile.syncGenerators in nx.json.

Dependencies

Each TypeScript project declares its third-party runtime dependencies in its own package.json. Build and test tooling shared across projects is defined in the root package.json.

To add a runtime dependency to a project, install it into that project:

pnpm

pnpm add some-npm-package --filter my-library

yarn

yarn workspace @my-scope/my-library add some-npm-package

npm

npm install --legacy-peer-deps some-npm-package -w packages/my-library

bun

bun add some-npm-package --cwd packages/my-library

You can also run your package manager’s plain add/install command from within the project’s directory.

To add a shared dev tool, install it at the workspace root:

pnpm

pnpm add -Dw some-dev-tool

yarn

yarn add -D some-dev-tool

npm

npm install --legacy-peer-deps -D some-dev-tool

bun

bun add -D some-dev-tool

Note

Biome’s noUndeclaredDependencies lint rule enforces that a project’s source only imports packages declared in its own package.json. Config files, build scripts and tests are exempt, so shared tooling can stay at the root.

Catalogs

For package managers which support catalogs (pnpm, yarn and bun), generators record each version in the catalog and reference it with the catalog: protocol (eg "zod": "catalog:"), so the catalog is the single source of truth for versions regardless of which project declares the dependency. This helps you to follow a single version policy, avoiding type conflicts and multiple copies of packages in deployment bundles.

When you add a new dependency yourself, keep it in the catalog too:

pnpm

The workspace sets catalogMode: strict, so pnpm add records the version in the catalog and references it automatically — no extra steps.

pnpm add some-npm-package --filter my-library

yarn

yarn’s catalog: protocol only references an existing catalog entry — it cannot create one — so record the version first.

1. Add the version under catalog in .yarnrc.yml:

   .yarnrc.yml

   catalog:
     some-npm-package: ^1.0.0

2. Reference it from the project:

   yarn workspace @my-scope/my-library add some-npm-package@catalog:

bun

bun’s catalog: protocol only references an existing catalog entry — it cannot create one — so record the version first.

1. Add the version under catalog in the root package.json:

   package.json

   {
     "catalog": {
       "some-npm-package": "^1.0.0"
     }
   }

2. Reference it from the project:

   bun add some-npm-package@catalog: --cwd packages/my-library

Aligning versions on npm

npm has no catalog feature, so versions are declared directly in each package.json. To keep them consistent across projects, we recommend syncpack (npx syncpack lint).

Opting out of catalogs

Catalogs are enabled by default. To turn them off, create your workspace with --catalog false:

pnpm

pnpm create @aws/nx-workspace my-project --catalog false

yarn

yarn create @aws/nx-workspace my-project --catalog false

npm

npm create @aws/nx-workspace -- my-project --catalog false

bun

bun create @aws/nx-workspace my-project --catalog false

Or set it in aws-nx-plugin.config.mts at any time:

aws-nx-plugin.config.mts

export default {
  packageManager: {
    catalogs: false,
  },
} satisfies AwsNxPluginConfig;

With catalogs disabled, generators write dependency versions directly into each project’s package.json, and keeping versions aligned across projects is your responsibility.

Declaring all dependencies at the root

If you prefer declaring every dependency in the root package.json only (no per-project dependency declarations), turn off the lint rule in the workspace biome.json:

biome.json

{
  "linter": {
    "rules": {
      "correctness": {
        "noUndeclaredDependencies": "off"
      }
    }
  }
}

Projects resolve root-installed packages at build time, so everything still builds — you give up per-project manifests as an accurate record of each project’s dependencies (which matters if you later publish a project or split the repo).

Runtime Code

When you use your TypeScript project as runtime code (for example as the handler for an AWS Lambda function), it’s recommended that you use a tool such as Rolldown to bundle your project, since this can tree-shake to ensure that only the dependencies your project actually references are included.

You can achieve this by adding a target such as the following to your project.json file:

{
  ...
  "targets": {
    ...
    "bundle": {
      "cache": true,
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/packages/my-library/bundle"],
      "options": {
        "command": "rolldown -c rolldown.config.ts"
      }
    },
  },
}

And adding the rolldown.config.ts file as follows:

rolldown.config.ts

import { defineConfig } from 'rolldown';

export default defineConfig([
  {
    input: 'src/index.ts',
    output: {
      file: '../../dist/packages/my-library/bundle/index.js',
      format: 'cjs',
      inlineDynamicImports: true,
    },
  },
]);

Bundle Configuration

Note that in the above target, we chose src/index.ts as our entrypoint for the bundle, which means that code exported from this file will be included in the bundle, along with all of its dependencies.

Lambda Functions

If you’re building an AWS Lambda function, check out the ts#lambda-function generator as this configures bundling for you, as well as generating infrastructure and adding observability and type-safety.

Building

Your TypeScript project is configured with a build target (defined in project.json), which you can run via:

pnpm

pnpm nx build <project-name>

yarn

yarn nx build <project-name>

npm

npx nx build <project-name>

bun

bunx nx build <project-name>

Where <project-name> is the fully qualified name of your project.

The build target will compile, lint and test your project.

Build output can be found in the root dist folder in your workspace, inside a directory for your package and target, for example dist/packages/<my-library>/tsc

To build all of the projects in your workspace, run:

pnpm

pnpm nx run-many --target build

yarn

yarn nx run-many --target build

npm

npx nx run-many --target build

bun

bunx nx run-many --target build

Or use the shorthand command:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Testing

Vitest is configured for testing your project.

Writing Tests

Tests should be written in .spec.ts or .test.ts files, co-located in your project’s src folder.

For example:

• Directorysrc

  • hello.ts Library source code
  • hello.spec.ts Tests for hello.ts

Vitest provides Jest-like syntax for defining tests, with utilities such as describe, it, test and expect.

hello.spec.ts

import { sayHello } from './hello.js';

describe('sayHello', () => {

  it('should greet the caller', () => {
    expect(sayHello('Darth Vader')).toBe('Hello, Darth Vader!');
  });

});

For more details about how to write tests, and features such as mocking dependencies, refer to the Vitest documentation

Running Tests

Tests will run as part of the build target for your project, but you can also run them separately by running the test target:

pnpm

pnpm nx test <project-name>

yarn

yarn nx test <project-name>

npm

npx nx test <project-name>

bun

bunx nx test <project-name>

You can run an individual test or suite of tests using Vitest’s -t flag. Pass it after a -- separator so Nx forwards it to Vitest rather than consuming it as its own --target option:

pnpm

pnpm nx test <project-name> -- -t 'sayHello'

yarn

yarn nx test <project-name> -- -t 'sayHello'

npm

npx nx test <project-name> -- -t 'sayHello'

bun

bunx nx test <project-name> -- -t 'sayHello'

VSCode Integration

If you are a VSCode user, we recommend installing the Vitest Runner for VSCode that actually works extension, which allows you to run, watch or debug tests from your IDE.

Linting

TypeScript projects use Biome for linting and formatting. Biome is configured in the workspace root biome.json file — changes to this apply to all TypeScript projects in your workspace and ensure consistency.

Running the Linter

To invoke the linter to check your project, you can run the lint target.

pnpm

pnpm nx lint <project-name>

yarn

yarn nx lint <project-name>

npm

npx nx lint <project-name>

bun

bunx nx lint <project-name>

Fixing Lint Issues

The majority of linting or formatting issues can be fixed automatically by running with the --configuration=fix argument.

pnpm

pnpm nx lint <project-name> --configuration=fix

yarn

yarn nx lint <project-name> --configuration=fix

npm

npx nx lint <project-name> --configuration=fix

bun

bunx nx lint <project-name> --configuration=fix

Similarly if you would like to fix all lint issues in all packages in your workspace, you can run:

pnpm

pnpm nx run-many --target lint --all --configuration=fix

yarn

yarn nx run-many --target lint --all --configuration=fix

npm

npx nx run-many --target lint --all --configuration=fix

bun

bunx nx run-many --target lint --all --configuration=fix

Shorthand Command

This has a shorthand command from the root of your workspace:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Skipping Lint Issues

To avoid linting issues slowing you down during development (particularly if you have non auto-fixable issues in your project), you can run a build with the skip-lint configuration:

pnpm

pnpm nx run-many --target build --configuration=skip-lint

yarn

yarn nx run-many --target build --configuration=skip-lint

npm

npx nx run-many --target build --configuration=skip-lint

bun

bunx nx run-many --target build --configuration=skip-lint

This skips the lint target entirely during build.

Shorthand Command

This has a shorthand command from the root of your workspace:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint