Skip to content

Latest commit

 

History

History
122 lines (74 loc) · 7.26 KB

README.md

File metadata and controls

122 lines (74 loc) · 7.26 KB
Raw

Blueprint CircleCI

Blueprint is a React-based UI toolkit for the web.

It is optimized for building complex, data-dense web interfaces for desktop applications. If you rely heavily on mobile interactions and are looking for a mobile-first UI toolkit, this may not be for you.

View the full documentation ▸

Read our FAQ on the wiki ▸

Read the introductory blog post ▸

Support question? We use the blueprintjs tag on Stack Overflow ▸

🚧 2.0 in development 🚧

The master branch of this repository is currently being used for development of the next major version of Blueprint. See the 2.0.0 milestone to track progress.

To make a contribution that you wish to have released in a 1.x version of any @blueprintjs package, please submit a PR to the release/1.x branch.

Packages

This repository contains multiple projects in the packages/ directory that fall into 3 categories:

Libraries

These are the component libraries we publish to NPM.

  • npm – Core styles & components.
  • npm – Components for interacting with dates and times.
  • npm – Documentation theme for Documentalist data.
    • Note: this is being renamed to @blueprintjs/docs-theme in 2.0.
  • npm – Scalable interactive table component.
  • npm – Incubator and staging area for new components still under initial development.

Applications

These are hosted on GitHub Pages as static web applications:

  • docs-app – Documentation site at blueprintjs.com/docs
  • landing-app – Landnig page at blueprintjs.com

These are used as development playground environments:

  • table-dev-app – demo page that supports manual testing of all table features

Build tooling

These packages define development dependencies and contain build configuration. They adhere to the standard NPM package layout, which allows us to keep clear API boundaries for build configuration and isolate groups of devDependencies. They are published to NPM in order to allow other Blueprint-related projects to use this infrastructure outside this monorepo.

  • npm
  • npm
  • npm
  • npm
  • npm

Development

Lerna manages inter-package dependencies in this monorepo. Builds are orchestrated via lerna run and NPM scripts.

Prerequisites: Node.js v8+, Yarn v1.0+

One-time setup

After cloning this repo, run:

  1. yarn to install all dependencies.
  2. yarn verify to ensure you have all the build tooling working properly.

Incorporating upstream changes

If you were previously in a working state and have just pulled new code from master:

  • If there were package dependency changes, run yarn at the root.
    • This command is very quick if there are no new things to install.
  • Run yarn compile to get the latest built versions of the library packages in this repo.
    • This command is quicker than yarn verify since it doesn't build the application packages (docs-app, landing-app, etc.) or run tests

Developing libraries

Each library has its own dev script which you can run to watch changes to that package and run the docs application with webpack-dev-server: yarn dev:core, yarn dev:datetime, etc.

  • One exception is table—since it has its own dev application, the dev:table script doesn't run the docs site.
    • Run the table dev application using yarn dev in the packages/table-dev-app folder.
  • You may also choose to watch changes across all packages by running yarn dev:all from the root directory.

Updating dependencies

  1. Edit the package.json where you wish to change dependencies.
  2. Run yarn at the root to update lockfiles.
  3. Commit the result.

Updating documentation

Much of Blueprint's documentation lives inside source code as JSDoc comments in .tsx files and KSS markup in .scss files. This documentation is extracted and converted into static JSON data using documentalist.

If you are updating documentation sources (not the docs UI code which lives in packages/docs-app or the docs theme in packages/docs-theme), you'll need to run yarn compile from packages/docs-data to see changes reflected in the application.

Updating icons

The One-time setup and Incorporating upstream changes steps should produce the generated source code in this repo used to build the icons documentation. This is sufficient for most development workflows.

If you are updating icons or adding new ones, you'll need to run yarn compile in packages/icons to see those changes reflected before running any of the dev scripts.

Contributing

Looking for places to contribute to the codebase? Check out the "help wanted" label.

Read about our contribution guidelines and development practices to give your PR its best chance at getting merged.

License

This project is made available under the Apache-2.0 License.