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/, e.g. /packages/loremipsum.

Package setup

Copy the following files from the datetime package into the loremipsum package, leaving them untouched:

• .npmignore
• LICENSE
• karma.conf.js

package.json

Copy/paste the package.json from the datetime 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.
• "keywords" - keep at least "palantir" and "blueprint", and add other relevant keywords.
• "dependencies" - make sure to add "@blueprintjs/core" as a dependency to loremipsum - this gives us access to core features. keep/delete other packages as needed (quick note - "tslib" is an easy win that emits smaller bundles; best to leave it in).
• "peerDependencies" - delete this since core (which is a dependency) specifies the relevant peer deps.

README.md

Add a README.md to document the responsibilities of that package - you can probably copy/paste from table or datetime and modify accordingly.

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 from datetime and change things accordingly:

1. Replace

       entry: {
   -        core: ...
   +        loremipsum: ...
       }

2. Replace

       output: {
   -       library: ["Blueprint", "Core"],
   +       library: ["Blueprint", "Loremipsum"],
       }

src/

Now we'll setup the src/ folder.

1. Copy/paste the tsconfig.json, tsconfig.cjs.json from datetime.
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). Modify the index.md to suit the new package. Our docs files conform to Documentalist.
5. Add a link to your docs page in /packages/docs-app/src/_nav.md:

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

Updating the docs application

1. Add examples in /packages/docs-app/src/examples (e.g. creating a loremipsum-examples directory).
2. Add @blueprintjs/loremipsum as a dependency in /packages/docs-app/package.json.
3. run yarn from the top-level folder to link loremipsum to docs-app.
4. Update /packages/docs-app/src/tags/reactExamples.ts to include your examples:

    import * as LabsExamples from "../examples/labs-examples";
   +import * as LoremIpsumExamples from "../examples/loremipsum-examples";
    import * as TableExamples from "../examples/table-examples";
   
   ...
   
    addPackageExamples("labs", LabsExamples as any);
   +addPackageExamples("loremipsum", LoremIpsumExamples as any);
    addPackageExamples("table", TableExamples as any);

test/

The only things you really have to do here are:

1. Create a test/tsconfig.json file (you can copy/paste the datetime one).
2. Have an index.ts file that imports or otherwise runs all your tests.

blueprint-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.

Firstly, lerna will automatically pick up loremipsum as a package and run commands on it by virtue of it being inside /packages/. You'll now want to add a dev command for it in the top-level /package.json file:

  "scripts": {
+   "dev:loremipusm": "lerna run dev --parallel --scope '@blueprintjs/{core,loremipsum}'",
  }

publishing your new package from CircleCI

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

jobs:
  dist-libs:
    steps:
      - persist_to_workspace:
          paths:
+           - packages/loremipsum/dist

+  test-loremipsum:
+    docker:
+      - image: circleci/node:8
+    steps:
+      - checkout
+      - attach_workspace:
+          at: '.'
+      - restore_cache:
+          key: v1-dependency-cache-{{ checksum "yarn.lock" }}
+      - run: yarn lerna run test --scope '@blueprintjs/loremipsum'

workflows:
  compile_lint_test_dist_deploy:
    jobs:
+      - test-loremipsum:
+          requires: [compile-libs]
      - deploy-preview:
          requires:
+            - test-loremipsum

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