Happy path: Publishing a Lit-based custom element to npmjs.com

Do you have an excellent idea for a custom web-based widget but are unsure about the tools and where to start building?

In this article, I'll go through the steps of building a custom element using TypeScript and Lit and publish it to npmjs.com. I wrote this when creating a timeline component of my own.

This article is not exactly a tutorial; it is written more as a quick "command reference" on how to do the things needed to be done when you create, build and publish a custom element to npmjs.com.

Starting the journey

I've used GitHub CLI and Visual Studio Code with Dev Containers and Ubuntu Multipass to create a virtual Linux environment for the project. Still, I won't detail how to set them up here and continue on my happy path.

First, we need to log in using GitHub CLI.

gh auth login

Create a new GitHub project for the custom element. Use the TypeScript project starter from the Lit project and clone it locally.

gh repo create my-custom-element --public -p lit/lit-element-starter-ts
gh repo clone my-custom-element

Using Visual Studio Code and Dev Containers is a good way to create an isolated environment for development. I used the Alpine "Node.js & TypeScript" (16-bullseye) environment as the basis here.

The 'Running in circles' part

Then the fun part: development. Running VS Code and Chrome browser, you get an environment to build. The template introduces src/my-element.ts which you rename to your component. Find something unique, and remember the dash.

Running the TS compiler in watch mode on the background.

npm run build:watch &

Most likely you start a server in port 8000 and view it in your browser while developing.

npm run serve

To run the validation tests

npm test

... and keep coding and testing.

Going public

I am publishing to npmjs.com and already had an account there. I edited the package.json metadata and updated the version to 1.0.0.

A typical workflow of mine making small fine-grained changes and committing to Git with an occasional push:

git add . && git commit -m "some changes" 
git push

Before the first publication, I needed to log in and make the package explicitly public:

npm login
npm publish --access=public

Once happy with the iterative changes, just push it public

npm version patch && npm publish

You have arrived

There you have it. Now using the element i standard way, you just use:

npm install @myorg/my-element

EDIT: (Jan 4, 2023) There is now Part 2 describing how to make a Vaadin Java component API for this custom element.

Enjoy the trip!