Skip to main content

Publishing a DeviceScript package

Using npm, GitHub releases, or other package manager is the recommended way to share your DeviceScript code. The process is very similar to publishing packages for node.js/web on npm.

Here are some examples of custom packages:

TL;DR: Creating a new package​

  • install command line tools: npm install -g @devicescript/cli
  • install yarn if you don't have it: npm install -g yarn
  • create folder for your package: mkdir devicescript-my-package (best if it starts with devicescript-)
  • in that folder run devs init --yarn and then devs add npm
  • run VS Code: code .
  • go to "Source Control" side panel, select "Publish to GitHub"

Now you can start building your library.

To publish to npm use yarn publish - it will ask you for version, tag the repo, and publish. Don't forget to git push --tags.

Getting started​

To create a DeviceScript library from your project, run this command or use DeviceScript: Add npm... from the command palette in Visual Studio Code.

yarn devs add npm

This will:

  • remove the "private" field from package.json
  • add "devicescript": { "library": true } (this is required)
  • set "main": "src/index.ts" (src/index.ts is created if missing)
  • set "files" field
  • add "license"
  • add "keywords": ["devicescript"] - keep this so npm search works better!
  • add "author" and "repository" if they can be inferred

All of these can be of course edited in package.json afterwards.

Naming convention​

In particular it's recommended to name your package devicescript-something.

Publishing​

After this step, you can publish your package using your favorite npm publishing pipeline.

tip

A DeviceScript does not require any special build assets. You can create a GitHub release and use as a dependency in your projects.

npm install --save user/repo@version

TypeDoc​

The package templates also adds a script build:docs to generate an API documentation site using TypeDoc. The devicescript-pico-bricks is an example of this web site.

npm run build:docs

You can configure GitHub pages to use the generated site under ./docs.

Development notes​

Note that regular DeviceScript applications typically use src/main.ts (or src/mainSomething.ts) as the application entry point. This is typically, not the right choice for library entry point.

You can keep your src/main.ts file as an example or test for the library, but best to stick to "main": "src/index.ts" in package.json.