1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
<img height="204" src="https://cloud.githubusercontent.com/assets/464822/20228152/d3f36dc2-a804-11e6-80ff-51ada2d13ea7.png">
# [Blueprint](http://blueprintjs.com/) [](https://circleci.com/gh/palantir/workflows/blueprint)
Blueprint is a React-based UI toolkit for the web.
It is optimized for building complex, data-dense web interfaces for _desktop applications_ which run in modern browsers. This is not a mobile-first UI toolkit.
[**Read the introductory blog post ▸**](https://medium.com/@palantir/scaling-product-design-with-blueprint-25492827bb4a)
[**View the full documentation ▸**](http://blueprintjs.com/docs)
[**Try it out on CodeSandbox ▸**](https://codesandbox.io/p/sandbox/blueprint-sandbox-2023-fjo3z4)
[**Read frequently asked questions (FAQ) on the wiki ▸**](https://github.com/palantir/blueprint/wiki/Frequently-Asked-Questions)
## Changelog
Blueprint's change log and migration guides for major versions live on the repo's [Github wiki](https://github.com/palantir/blueprint/wiki/3.x-Changelog).
## 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.
- [](https://www.npmjs.com/package/@blueprintjs/core) – Core styles & components.
- [](https://www.npmjs.com/package/@blueprintjs/datetime) – Components for interacting with dates and times.
- [](https://www.npmjs.com/package/@blueprintjs/datetime2) – Next-generation timezone-aware components for interacting with dates and times.
- [](https://www.npmjs.com/package/@blueprintjs/icons) – Components for generating and displaying icons.
- [](https://www.npmjs.com/package/@blueprintjs/popover2) – Popover2 and Tooltip2 components.
- [](https://www.npmjs.com/package/@blueprintjs/select) – Components for selecting items from a list.
- [](https://www.npmjs.com/package/@blueprintjs/table) – Scalable interactive table component.
- [](https://www.npmjs.com/package/@blueprintjs/timezone) – Components for picking timezones (:warning: deprecated).
### Applications
These are hosted on GitHub Pages as static web applications:
- `docs-app` – Documentation site at blueprintjs.com/docs
- `landing-app` – Landing page at blueprintjs.com
These are used as development playground environments:
- `demo-app` – demo page that shows many components all on the same page in light and dark themes
- `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.
- [](https://www.npmjs.com/package/@blueprintjs/docs-theme) – Documentation theme for [Documentalist](https://github.com/palantir/documentalist) data.
- [](https://www.npmjs.com/package/@blueprintjs/eslint-config) – ESLint configuration used in this repo and recommended for Blueprint-related projects
- [](https://www.npmjs.com/package/@blueprintjs/eslint-plugin) – implementations for custom ESLint rules which enforce best practices for Blueprint usage
- [](https://www.npmjs.com/package/@blueprintjs/karma-build-scripts) – Karma test runner configuration
- [](https://www.npmjs.com/package/@blueprintjs/node-build-scripts) – various utility scripts for linting, working with CSS variables, and building icons
- [](https://www.npmjs.com/package/@blueprintjs/stylelint-plugin) – implementations for custom stylelint rules which enforce best practices for Blueprint usage
- [](https://www.npmjs.com/package/@blueprintjs/test-commons) – various utility functions used in Blueprint test suites
- [](https://www.npmjs.com/package/@blueprintjs/tslint-config) – TSLint configuration used in this repo and recommended for Blueprint-related projects (should be installed by `@blueprintjs/eslint-config`, not directly)
- [](https://www.npmjs.com/package/@blueprintjs/webpack-build-scripts) – Webpack build configuration
## Contributing
Looking for places to contribute to the codebase?
First read the [contribution guidelines](https://github.com/palantir/blueprint/blob/develop/CONTRIBUTING.md),
then [check out the "help wanted" label](https://github.com/palantir/blueprint/labels/help%20wanted).
## Development
[Lerna](https://lerna.js.org/) manages inter-package dependencies in this monorepo.
Builds are orchestrated via `lerna run` and NPM scripts.
**Prerequisites**: Node.js v18+ (see version specified in `.nvmrc`), Yarn v1.22
### One-time setup
First, ensure you have `nvm` ([Node Version Manager](https://github.com/nvm-sh/nvm)) installed.
After cloning this repo, run:
1. `nvm use` to use the supported Node version for Blueprint development.
1. `yarn` to install all dependencies for the monorepo.
1. If running on Windows:
1. `npm install -g windows-build-tools` to install build tools globally
1. Ensure `bash` is your configured script-shell by running:<br />
`npm config set script-shell "C:\\Program Files\\git\\bin\\bash.exe"`
1. `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 `develop`:
- 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
There are a few ways to run development scripts, here they are listed from simplest to more advanced usage:
- Run `yarn dev` from the root directory to watch changes across all packages and run the docs application with webpack-dev-server.
- Alternately, most libraries have a corresponding dev script to run the docs app and watch changes to just that package:
- `yarn dev:core`
- `yarn dev:docs`
- `yarn dev:datetime`
- `yarn dev:datetime2`
- `yarn dev:popover2`
- `yarn dev:select`
- `yarn dev:table`
- Lastly, if you want to control exaclty which dev scripts are run and view the console output in the cleanest way, we recommend opening separate terminal windows or splits and running local package dev tasks in each one. This is the recommended workflow for frequent contributors and advanced developers. For example, to test changes in the core + icons packages, you would run the following in separate terminals:
- `cd packages/core && yarn dev`
- `cd packages/icons && yarn dev`
- `cd packages/docs-app && yarn dev`
### 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](https://github.com/palantir/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. For simplicity, an alias script `yarn docs-data` exists in the root to minimize directory hopping.
### Updating icons
The [One-time setup](#one-time-setup) and [Incorporating upstream changes](#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.
## License
This project is made available under the Apache 2.0 License.
|
