Skip to content

Commit

Permalink
[docs] fix CDN usage & bundle externals (#3276)
Browse files Browse the repository at this point in the history 
* update webpack externals

* update CDN guide in getting started

* push CDN section to the bottom (to avoid distraction)

* remove repeated install notes

* remove jquery
  • Loading branch information
@giladgray
giladgray authored Jan 10, 2019
1 parent ead1dc5 commit 1c89f7b
Show file tree
Hide file tree
Showing 2 changed files with 77 additions and 83 deletions.
152 changes: 72 additions & 80 deletions packages/docs-app/src/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,27 +2,20 @@

@## Installing Blueprint

@### NPM packages

Blueprint is available as a collection of NPM packages under the `@blueprintjs` scope.
Each package appears at the top level of the sidebar, along with its current version.
Blueprint is available as a collection of NPM packages under the `@blueprintjs`
scope. Each package appears at the top level of the sidebar to the left, along
with its current version.

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](http://semver.org/).

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

```sh
yarn add @blueprintjs/core
```

1. If you see `UNMET PEER DEPENDENCY` errors, you should manually install React (v15.3 or greater):
1. Install the core package and its peer dependencies with an NPM client like
`npm` or `yarn`, pulling in all relevant dependencies:

```sh
yarn add react react-dom
yarn add @blueprintjs/core react react-dom
```

1. After installation, you'll be able to import the React components in your application:
Expand All @@ -37,75 +30,32 @@ The `main` module exports all symbols from all modules so you don't have to impo
const myButton = React.createElement(Button, { intent: Intent.SUCCESS }, "button content");
```
1. Don't forget to include the main CSS file from each Blueprint package! Additionally, the
1. **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.
```html
<!-- 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>
```
```css.scss
// or, using node-style package resolution in a CSS file:
// using node-style package resolution in a CSS file:
@import "~normalize.css";
@import "~@blueprintjs/core/lib/css/blueprint.css";
@import "~@blueprintjs/icons/lib/css/blueprint-icons.css";
```
@### CDN consumption
Blueprint supports the venerable [unpkg CDN](https://unpkg.com). 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`, `classnames`, `dom4`, `react`, `react-dom`, `react-transition-group`, `popper.js`, and
`react-popper` are available at runtime.
```html
<!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@^3.0.0/lib/css/blueprint.css" rel="stylesheet" />
<link href="https://unpkg.com/@blueprintjs/icons@^3.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.14.1/dist/umd/popper.js"></script>
<script src="https://unpkg.com/react-popper@^1.0.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@blueprintjs/core@^3.0.0"></script>
<script src="https://unpkg.com/@blueprintjs/icons@^3.0.0"></script>
```html
<!-- or using plain old 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>
```
<div id="btn"></div>
<script>
const button = React.createElement(Blueprint.Core.Button, {
icon: "cloud",
text: "CDN Blueprint is go!",
});
ReactDOM.render(button, document.querySelector("#btn"));
</script>
</body>
</html>
```
<div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
<h4 class="@ns-heading">CDN-only usage</h4>
Blueprint can instead be quickly added to a page using the Unpkg CDN.
[See below for instructions](#blueprint/getting-started.cdn-consumption).
</div>
@## JS environment
Expand Down Expand Up @@ -181,11 +131,53 @@ ReactDOM.unmountComponentAtNode(myContainerElement);
Check out the [React API docs](https://facebook.github.io/react/docs/react-api.html) for more details.
You'll need to install React v15.3 or greater alongside Blueprint.
@## CDN consumption
```sh
npm install --save @blueprintjs/core react react-dom react-transition-group
```
Blueprint supports the venerable [unpkg CDN](https://unpkg.com). 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`, `classnames`, `dom4`, `react`, `react-dom`, `react-transition-group`, `popper.js`, and
`react-popper` are available at runtime.
```html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>Blueprint Starter Kit</title>
Import components from the `@blueprintjs/core` module into your project.
Don't forget to include the main CSS stylesheet too!
<!-- Style dependencies -->
<link href="https://unpkg.com/normalize.css@^7.0.0" rel="stylesheet" />
<!-- Blueprint stylesheets -->
<link href="https://unpkg.com/@blueprintjs/icons@^3.4.0/lib/css/blueprint-icons.css" rel="stylesheet" />
<link href="https://unpkg.com/@blueprintjs/core@^3.10.0/lib/css/blueprint.css" rel="stylesheet" />
</head>
<body>
<!-- Blueprint dependencies -->
<script src="https://unpkg.com/classnames@^2.2"></script>
<script src="https://unpkg.com/dom4@^1.8"></script>
<script src="https://unpkg.com/tslib@^1.9.0"></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.14.1/dist/umd/popper.js"></script>
<script src="https://unpkg.com/react-popper@^1.0.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/resize-observer-polyfill@^1.5.0"></script>
<!-- Blueprint packages (note: icons script must come first) -->
<script src="https://unpkg.com/@blueprintjs/icons@^3.4.0"></script>
<script src="https://unpkg.com/@blueprintjs/core@^3.10.0"></script>
<div id="btn"></div>
<script>
const button = React.createElement(Blueprint.Core.Button, {
icon: "cloud",
text: "CDN Blueprint is go!",
});
ReactDOM.render(button, document.querySelector("#btn"));
</script>
</body>
</html>
```
8 changes: 5 additions & 3 deletions packages/webpack-build-scripts/externals.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,16 @@ module.exports = externalize({
"@blueprintjs/timezone": ["Blueprint", "Timezone"],
"classnames": "classNames",
"dom4": "window",
"jquery": "$",
"moment": "moment",
"moment-timezone": "moment",
"popper.js": "Popper",
"react": "React",
"react-transition-group": "ReactTransitionGroup",
"react-day-picker": "DayPicker",
"react-dom": "ReactDOM",
"tslib": "tslib",
"react-popper": "ReactPopper",
"react-transition-group": "ReactTransitionGroup",
"resize-observer-polyfill": "ResizeObserver",
"tslib": "window",
});

/**
Expand Down

1 comment on commit 1c89f7b

@blueprint-bot
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[docs] fix CDN usage & bundle externals (#3276)

Previews: documentation | landing | table

Please sign in to comment.