Developing applications and libraries with pnpm

Classic project driven by package.json

The LifecyclePnpmNodeWithPackageJson is the standard development model where there is only a single JavaScript/TypeScript project and everything is configured in package.json.

Minimal configuration

build.gradle

import org.ysb33r.gradle.jse.pnpm.toolchains.JsePnpmToolchain
import org.ysb33r.gradle.jse.pnpm.dev.models.LifecyclePnpmNodeWithPackageJson

plugins {
 id 'org.ysb33r.jsecosystem.pnpm.dev' version '5.3.0-alpha.1'
}

jsEcosystem {
  toolchains {
    pnpm(JsePnpmToolchain) { (1)
    }
  }
}

jsProjects {
  lifecycleManagers {
    pnpm(LifecyclePnpmNodeWithPackageJson) { (2)
      toolchain = 'pnpm' (3)
    }
  }

  sourceSets {
    main { (4)
        lifecycle('pnpnm', LifecyclePnpmNodeWithPackageJson) (5)
    }
  }
}

1	A pnpm toolchain is required. See Toolchains for pnpm for more details on toolchains.
2	Create the lifecycle manager toolchain.
3	Create a source set. See Basics of configuring projects on how to configure source sets.
4	Tell Gradle that the specific source set will use pnpm and `package.json`.

Tasks

For the main source set, the following tasks will be added to Gradle lifecycles:

assemble: jseAssemble.
check: jseTest.

For a list of available tasks classes see Task classes

Publishing packages

There is currently not a registered task that will publish a package to a PNPM registry. This will probably be added in a future release. However, it is easy to implement your own by extending AbstractPnpmLifecycleTask

Running scripts in package.json

The lifecycle manager already implements tasks for handling certain scripts within the package.json file. However, for any other scripts that are not covered by a defined task, there is support for using a Gradle rule to run any script defined in the scripts block.

The format of the rule is jseRun<ScriptName><sourceSetName> or if the source set is called main it is simply jseRun<ScriptName>. If you have a script called lint you can use a task jseRunLint.

Workspace project driven by pnpm-workspace.yaml

The LifecyclePnpmNodeWithWorkspaces is the standard development model when working with a monorepo-style PNPM workspace. In this model Gradle wraps the root workspace and there are multiple JavaScript/TypeScript projects in the workspace. The project is configured with pnpm-workspace.yaml and subprojects are configured with package.json

In most cases Gradle will just delegate to pnpm which will then perform all of the building. Gradle reads th tasks field from pnpm-workspace.yaml to determine the toplevel Gradle tasks. As a configurable option, Gradle can also scan every package defined in the packages field and create tasks for run scripts in the package.json files.

Minimal configuration

build.gradle

import org.ysb33r.gradle.jse.pnpm.toolchains.JsePnpmToolchain
import org.ysb33r.gradle.jse.pnpm.dev.models.LifecyclePnpmNodeWithWorkspaces

plugins {
 id 'org.ysb33r.jsecosystem.pnpm.dev' version '5.3.0-alpha.1'
}

jsEcosystem {
  toolchains {
    pnpm(JsePnpmToolchain) { (1)
    }
  }
}

jsProjects {
  lifecycleManagers {
    pnpm(LifecyclePnpmNodeWithWorkspaces) { (2)
      toolchain = 'pnpm' (3)
      noWorkspaceTreeTaskConversion() (4)
      convertWorkspaceTreeIntoTasks()  (5)
      convertMatchingPackagesIntoTasks 'mypackage', '@myscope/mypackage'  (6)
      convertMatchingPackagesIntoTasks ~/.*mypackage.*/  (7)
  }

  sourceSets {
    main { (8)
        lifecycle('pnpnm', LifecyclePnpmNodeWithWorkspaces) (9)
    }
  }
}

1	A pnpm toolchain is required. See Toolchains for pnpm for more details on toolchains.
2	Create the lifecycle manager toolchain.
3	Link the lifecycle to a toolchain
4	Do not scan the workspace’s packages for scripts. This is the default behaviour.
5	Scan all packages in the workspace for scripts and convert each package-script combination into a task.
6	Scan only the packages in the workspace that matche the given names and convert those package-script combinations into tasks.
7	Scan only the packages in the workspace that matches the given patterns and convert those package-script combinations into tasks.
8	Create a source set. See Basics of configuring projects on how to configure source sets.
9	Tell Gradle that the specific source set will use pnpm and `pnpm-workspace.yaml`.

Tasks

For the main source set, the following tasks will be added to Gradle lifecycles:

assemble: jseAssemble.
check: jseTest.

It convertWorkspaceTreeIntoTasks or convertMatchingPackagesIntoTask was configred a range of tasks starting with jseWsRun will be added. For the latter packages that have scopes will have it added into the task name. For example, running the foo script in a package @myscope/mypackage, the task name will be jseWsRun@myscopeMypackageFoo. Any /, :, or - will be removed and the following character will be capitalised.

For a list of available tasks classes see Task classes