Publish your library to npm – tutorial

Create a simple organization

In this tutorial, we publish the library under an npm organization to avoid naming conflicts.

To create a new organization, follow the npm documentation.

Generate an access token

To publish to npm manually, you need an access token that allows publishing a package under your newly created organization. To generate such a token, follow the npm guide.

For this tutorial, use a simplified security configuration:

• Enable the Bypass two-factor authentication (2FA) option.

• Set both the general permissions and organization permissions for the token to Read and write.

Set up the publishing plugin

This tutorial uses the official npm-publish plugin to help with publishing to npm. To learn more about the plugin and available configuration options, see the plugin's documentation.

Add the plugin to your Kotlin Multiplatform project:

1. Open your library module's build.gradle.kts file.

2. Add the following line to the plugins {} block:

   // <module directory>/build.gradle.kts plugins { kotlin("npm-publish") version "3.6.0" }

3. Add the following configuration. Make sure to customize the values for your library. The only required parameters are organization, authToken, packageName, and version. The rest is given as an extended example:

   // <module directory>/build.gradle.kts npmPublish { organization = "organization_name_without_the_@_sign" registries { npmjs { // You'll pass your npm token as this environment variable // when you run the command to publish the package authToken = System.getenv("NPM_TOKEN") } } packages { named("js") { version = "0.0.1" packageName = "greetings" readme = file("../README.md") packageJson { license = "Apache 2.0" homepage = "https://github.com/Kotlin/kotlin-multiplatform-web-library#readme" description = "Shared Kotlin/JS Greetings library" keywords = listOf("kotlin", "kotlin-js", "greetings", "shared", "api") author { name = "Kotlin Developer Advocate" url = "https://github.com/kotlin-hands-on/" } contributors = listOf( Person { name = "John Smith" email = "john.smith@example.com" url = "https://github.com/johnsmith" }, ) repository { type = "git" url = "https://github.com/Kotlin/kotlin-multiplatform-web-library.git" } } } } }

The important settings in the npmPublish {} block are:

• The organization parameter and the registries {} block specify authentication details. In this case, we use the main npm registry and the name of the NPM_TOKEN variable that should hold the token when the publishing task is run.

• The packageName and version parameters define the mandatory package options:

  • The version parameter can be omitted to use your module's version as the default value.

  • The packageName parameter can be omitted to use the name of your module as the default value.

• The packageJson {} block holds various metadata.

Troubleshooting

A couple of things that can often go wrong with manual publication:

• Keep track of the version field in the build.gradle.kts configuration: npm fails publication if the package was already published with the same or earlier version.

• When generating a token for an organization-scoped package, make sure to set both general and organization permissions.

Create a GitHub Actions workflow file

Create a .github/workflows/publish.yml file that configures the GitHub action:

Once you commit and push this file into the GitHub repository hosting your project, the workflow runs whenever you create a GitHub release in that repository.

Set up GitHub Actions as your Trusted Publisher

Now that you have a workflow published, you can use the GitHub Action to add a Trusted Publisher to your npm package:

1. Open the published package page.

2. Open the Settings tab and find the Trusted Publisher section.

3. Under Select your publisher, click the GitHub Actions button.

4. Fill out the form:

   • your GitHub name (or organization)

   • the repository name

   • the name of the workflow file (in this tutorial, we've used publish.yml).

5. Click the Setup connection button.

The created connection is then listed in the Trusted Publishers section of your package's settings, which means that the workflow with the specified coordinates is now authorized to publish to npm.

Create a release on GitHub

With the workflow and the Trusted Publisher connection set up, you're now ready to trigger publishing by creating a GitHub release:

1. Set the package version in the build.gradle.kts configuration to the one you want to publish.

2. Go to your GitHub repository.

3. In the right sidebar, click Releases.

4. Click the Draft a new release button (or the Create a new release button if you haven't created a release for this repository before).

5. Create or select a Git tag (match the module's version if possible to keep the numbering consistent across systems).

6. Set the release title (it's handy to name the release same as the tag).

   To keep track of everything, you may want for the version in the tag to be the same as the version number of the library that you specified in the build.gradle.kts file.

   

7. Click the Publish release button.

To check whether the Action was triggered, click the Actions tab at the top of your GitHub repository's page. You should see that the newly published release triggered a run of the publishing workflow. Click on the workflow to see the logs of the publication task.

When the workflow run is complete, the new version of your package should be listed on your package's page in the npm registry.