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

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

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:

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

karma.conf.js

Copy/paste the karma.config.js from datetime and change things accordingly:

         webpack: Object.assign({}, baseConfig.webpack, {
             entry: {
-                datetime: [
+                loremipsum: [
                     ...,
-                    path.resolve(__dirname, "dist/blueprint-datetime.css"),
+                    path.resolve(__dirname, "dist/blueprint-loremipsum.css"),
                 ],
             },

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.

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 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);

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

   +@import "~@blueprintjs/select/dist/blueprint-loremipsum.css";

test/

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

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.

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,labs,table}'",
// add your package to the dist:libs task
+    "dist:libs": "lerna run dist --parallel --scope '@blueprintjs/{core,datetime,docs,labs,loremipusm,table}'",
  }

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!