Creating a new package

This document describes how to create and publish a new Blueprint package to NPM.

Package setup

In this example, our new package is named @blueprintjs/time-travel.

To start, create a new directory in this repository at /packages/time-travel.

Copy the following files from packages/core into the new package directory, leaving them untouched:

• .npmignore
• LICENSE

package.json

Copy/paste the package.json file from the core package and change things accordingly:

• "name" - "@blueprintjs/time-travel"
• "version" - "0.1.0"
  • usually you should start new packages in the v0.x range to allow for development flexibility while you iterate on and stabilize the public API
• "description" - enter a short description of the package.
• "style" - lib/css/blueprint-time-travel.css.
• "unpkg" - dist/time-travel.bundle.js.
• "sideEffects" - replace with ["**/*.css"]
• "keywords" - keep at least "palantir" and "blueprint", and add other relevant keywords.
• "dependencies" - remove all dependencies except for "tslib". Add a dependency on "@blueprintjs/core".

README.md

Add a README.md to document the responsibilities of and motivations behind the new package. Review the other package READMEs to match their style and content.

Be aware that the npmjs.com listing for each package renders this README in its UI (example).

webpack.config.js

Copy over the webpack.config.js file from packages/core and change things accordingly:

    entry: {
-        core: ...
+        "time-travel": ...
    },
    ...,
    output: {
-       library: ["Blueprint", "Core"],
+       library: ["Blueprint", "TimeTravel"],
    }

karma.conf.js

Create a boilerplate test config at packages/time-travel/karma.conf.js:

/*
 * Copyright 2022 Palantir Technologies, Inc. All rights reserved.
 */

const { createKarmaConfig } = require("@blueprintjs/karma-build-scripts");

module.exports = function (config) {
    const baseConfig = createKarmaConfig({
        dirname: __dirname,
    });
    config.set(baseConfig);
    config.set({
        // overrides here
    });
};

src/

Now we'll setup the src/ folder.

1. Copy over the tsconfig.json file from packages/core.
2. Write your main package export in src/index.ts.
3. Write your main styles in src/blueprint-time-travel.scss.
4. Add an index.md file (copy from datetime/src/). Modify the index.md to suit the new package. Our documentation files use Documentalist syntax & layout.

Updating the docs application

1. Add a link to your docs page in /packages/docs-app/src/_nav.md:

   # this will look for time-travel/src/index.md
   +@page time-travel

2. Create a time-travel-examples directory in /packages/docs-app/src/examples, and add example usage components.
3. Add @blueprintjs/time-travel as a dependency in /packages/docs-app/package.json.

      "dependencies": {
   +    "@blueprintjs/time-travel": "^0.1.0",
      }

4. Run yarn from the repository root folder to link time-travel to docs-app.
5. Update /packages/docs-app/src/tags/reactExamples.ts to include your examples:

    import * as SelectExamples from "../examples/select-examples";
   +import * as TimeTravelExamples from "../examples/time-travel-examples";
    import * as TableExamples from "../examples/table-examples";
   
   ...
   
    ...getPackageExamples("select", SelectExamples as any);
   +...getPackageExamples("time-travel", TimeTravelExamples as any);
    ...getPackageExamples("table", TableExamples as any);

6. Import the styles in docs-app/src/index.scss:

   +@import "~@blueprintjs/time-travel/lib/css/blueprint-time-travel.css";

test/

1. Create a test/tsconfig.json file (you can copy/paste the one from packages/datetime).
2. Have an index.ts file that imports or otherwise runs all your tests.
3. Copy/paste test/isotest.js from datetime. You can usually just use it as is (replacing the datetime package name). This is to hook up Blueprint's isomorphic testing framework to ensure your package components can render from the server-side.

Repo-wide setup

💁 Confirm that things are hooked up by running yarn verify from the top-level folder.

Now that the package itself is setup, there's just a few steps to get it working within the entire Blueprint monorepo.

You'll want to add a few things to the top-level /package.json file:

  "scripts": {
// OPTIONAL: add a dev task for your package (include other blueprint dependencies within the scope)
+    "dev:time-travel": "lerna run dev --parallel --scope '@blueprintjs/{time-travel,docs-app}'",
// add your package to the dist:libs task
-    "dist:libs": "lerna run dist --parallel --scope '@blueprintjs/{core,...,timezone}'",
+    "dist:libs": "lerna run dist --parallel --scope '@blueprintjs/{colors,...,timezone,time-travel}'",
  }

Publishing your new package from CircleCI

Lastly you'll want to modify the CircleCI build script to run the package's tests. Open up /.circleci/config.yml and make the following changes:

   test-react-16: &test-react
   ...
             6) yarn lerna run --scope "@blueprintjs/table" test:karma ;; \
             7) yarn lerna run --scope "@blueprintjs/timezone" test:karma ;; \
+            8) yarn lerna run --scope "@blueprintjs/time-travel" test:karma ;; \
             esac
           when: always
   ...

After that, commit and merge the change, and your new package will be published!