Creating a new package

This document describes how to create and publish a new Blueprint package to NPM (e.g. @blueprintjs/core, @blueprintjs/table, etc).

To start, create a new directory in /packages/, for example /packages/loremipsum.

Package setup

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

• .npmignore
• LICENSE

package.json

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

• "name" - "@blueprintjs/loremipsum"
• "version" - "1.0.0"
• "description" - enter a short description of the package.
• "style" - the convention is to use dist/blueprint-loremipsum.css.
• "unpkg" - dist/loremipsum.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 uses the README in its UI—for example: https://www.npmjs.com/package/@blueprintjs/table.

webpack.config.js

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

    entry: {
-        core: ...
+        loremipsum: ...
    },
    ...,
    output: {
-       library: ["Blueprint", "Core"],
+       library: ["Blueprint", "Loremipsum"],
    }

karma.conf.js

Create a boilerplate test config at packages/loremipsum/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/paste 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-loremipsum.scss.
4. Add an index.md file (copy from datetime/src/). Modify the index.md to suit the new package. Our docs files conform to Documentalist.

Updating the docs application

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

   # this will look for loremipsum/src/index.md
   +@page loremipsum

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

      "dependencies": {
   +    "@blueprintjs/loremipsum": "^1.0.0",
      }

4. Run yarn from the top-level folder to link loremipsum 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 LoremIpsumExamples from "../examples/loremipsum-examples";
    import * as TableExamples from "../examples/table-examples";
   
   ...
   
    ...getPackageExamples("select", SelectExamples as any);
   +...getPackageExamples("loremipsum", LoremIpsumExamples as any);
    ...getPackageExamples("table", TableExamples as any);

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

   +@import "~@blueprintjs/loremipsum/dist/blueprint-loremipsum.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": {
// add a dev task for your package (include other blueprint dependencies within the scope)
+    "dev:loremipusm": "lerna run dev --parallel --scope '@blueprintjs/{core,loremipsum}'",
-    "dist:libs": "lerna run dist --parallel --scope '@blueprintjs/{core,datetime,docs,table}'",
// add your package to the dist:libs task
+    "dist:libs": "lerna run dist --parallel --scope '@blueprintjs/{core,datetime,docs,loremipusm,table}'",
  }

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
   ...
             5) yarn lerna run --scope "@blueprintjs/table" test:karma ;; \
             6) yarn lerna run --scope "@blueprintjs/timezone" test:karma ;; \
+            7) yarn lerna run --scope "@blueprintjs/loremipsum" test:karma ;; \
             esac
           when: always
   ...

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