Skip to content

Latest commit

 

History

History
191 lines (146 loc) · 7.01 KB

getting-started.md

File metadata and controls

191 lines (146 loc) · 7.01 KB
Raw

@# Getting started

@## Installing Blueprint

@### NPM packages

Blueprint is available as a collection of NPM packages under the @blueprintjs scope. The full package list and their latest versions appear under the Releases dropdown above.

Each package contains a CSS file and a collection of CommonJS modules exposing React components. The main module exports all symbols from all modules so you don't have to import individual files (though you can if you want to). The JavaScript components are stable and their APIs adhere to semantic versioning.

  1. Install the core package with an NPM client like npm or yarn, pulling in all relevant dependencies:

    yarn add @blueprintjs/core

  2. If you see UNMET PEER DEPENDENCY errors, you should manually install React:

    yarn add react react-dom react-transition-group

  3. After installation, you'll be able to import the React components in your application:

    import { Button, Intent, Spinner } from "@blueprintjs/core";

// using JSX:
const mySpinner = <Spinner intent={Intent.PRIMARY} />;

// use React.createElement if you're not using JSX.
const myButton = React.createElement(Button, { intent: Intent.SUCCESS }, "button content");

  4. Don't forget to include the main CSS file from each Blueprint package! Additionally, the resources/ directory contains supporting media such as fonts and images.

    <!-- in plain old HTML -->
<!DOCTYPE HTML>
<html>
  <head>
    ...
    <!-- include dependencies manually -->
    <link href="path/to/node_modules/normalize.css/normalize.css" rel="stylesheet" />
    <link href="path/to/node_modules/@blueprintjs/core/lib/css/blueprint.css" rel="stylesheet" />
    <link href="path/to/node_modules/@blueprintjs/icons/lib/css/blueprint-icons.css" rel="stylesheet" />
    <!-- NOTE: blueprint-icons.css file must be included alongside blueprint.css! -->
    ...
  </head>
  ...
</html>
    // or, using node-style package resolution in a CSS file:
@import "~@blueprintjs/core/lib/css/blueprint.css";
@import "~@blueprintjs/icons/lib/css/blueprint-icons.css";

@### CDN consumption

Blueprint supports the venerable unpkg CDN. Each package provides a UMD dist/[name].bundle.js file containing the bundled source code. The UMD wrapper exposes each library on the Blueprint global variable: Blueprint.Core, Blueprint.Datetime, etc.

These bundles do not include external dependencies; your application will need to ensure that normalize.css, react, react-dom, react-transition-group, classnames, popper.js, and react-popperare available at runtime.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width">
    <title>Blueprint Starter Kit</title>
    <link href="https://unpkg.com/normalize.css@^7.0.0" rel="stylesheet" />
    <link href="https://unpkg.com/@blueprintjs/core@^2.0.0/lib/css/blueprint.css" rel="stylesheet" />
    <link href="https://unpkg.com/@blueprintjs/icons@^2.0.0/lib/css/blueprint-icons.css" rel="stylesheet" />
  </head>
  <body>
    <script src="https://unpkg.com/classnames@^2.2"></script>
    <script src="https://unpkg.com/dom4@^1.8"></script>
    <script src="https://unpkg.com/react@^16.2.0/umd/react.production.min.js"></script>
    <script src="https://unpkg.com/react-dom@^16.2.0/umd/react-dom.production.min.js"></script>
    <script src="https://unpkg.com/react-transition-group@^2.2.1/dist/react-transition-group.min.js"></script>
    <script src="https://unpkg.com/popper.js@^1.12.6/dist/umd/popper.js"></script>
    <script src="https://unpkg.com/react-popper@~0.7.4/dist/react-popper.min.js"></script>
    <script src="https://unpkg.com/@blueprintjs/core@^2.0.0"></script>
    <script src="https://unpkg.com/@blueprintjs/icons@^2.0.0"></script>

    <div id="btn"></div>
    <script>
      const button = React.createElement(Blueprint.Core.Button, {
        icon: "predictive-analysis",
        text: "CDN Blueprint is go!",
      });
      ReactDOM.render(button, document.querySelector("#btn"));
    </script>
  </body>
</html>

@## JS environment

@### Language features

Note that since the minimum supported version of React is v16, all of its JavaScript Environment Requirements apply to Blueprint as well. Blueprint components require the following ES2015 features:

  • Map
  • Set
  • Array.fill
  • Array.from

We recommend polyfilling these features using es6-shim or core-js.

@### DOM4

Blueprint relies on a handful of DOM Level 4 API methods: el.closest() and el.contains(). @blueprintjs/core depends on a polyfill library called dom4 to ensure these methods are available. This module is conditionally loaded if Blueprint is used in a browser environment.

@## TypeScript

Blueprint is written in TypeScript and therefore its own .d.ts type definitions are distributed in the NPM package and should be resolved automatically by the compiler. However, you'll need to install typings for Blueprint's dependencies before you can consume it:

# required for all @blueprintjs packages:
npm install --save @types/react @types/react-dom @types/react-transition-group

# @blueprintjs/datetime requires:
npm install --save @types/moment

Blueprint's declaration files require TypeScript 2.3+ for default generic parameter arguments: <P = {}>.

For more information, see [Understanding TypeScript](#blueprint/getting-started.understanding-typescript) below.

@## Vanilla JS APIs

JS components are built using React, but that does not limit their usage to just React applications. You can render any component in any JavaScript application with ReactDOM.render. Think of it like using a jQuery plugin.

import { Classes, Intent, Spinner } from "@blueprintjs/core";

const myContainerElement = document.getElementById("container");

// with JSX
ReactDOM.render(<Spinner className={Classes.SMALL} intent={Intent.PRIMARY} />, myContainerElement);

// with vanilla JS, use React.createElement
ReactDOM.render(
    React.createElement(Spinner, {
        className: Classes.SMALL,
        intent: Intent.PRIMARY,
    }),
    myContainerElement,
);

To remove the component from the DOM and clean up, unmount it:

ReactDOM.unmountComponentAtNode(myContainerElement);

Check out the React API docs for more details.

You'll need to install React 16.2+ alongside Blueprint.

npm install --save @blueprintjs/core react react-dom react-transition-group

Import components from the @blueprintjs/core module into your project. Don't forget to include the main CSS stylesheet too!