Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] fix CDN usage & bundle externals #3276

Merged
merged 5 commits into from
Jan 10, 2019
Merged

[docs] fix CDN usage & bundle externals #3276

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3f41728
update webpack externals
Jan 9, 2019
7aef027
update CDN guide in getting started
Jan 9, 2019
d2f8b78
push CDN section to the bottom (to avoid distraction)
Jan 9, 2019
9ec7949
remove repeated install notes
Jan 9, 2019
0261da9
remove jquery
Jan 10, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 72 additions & 80 deletions packages/docs-app/src/getting-started.md
View file
Open in desktop
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>
```
7 changes: 5 additions & 2 deletions packages/webpack-build-scripts/externals.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,14 @@ module.exports = externalize({
"jquery": "$",
Copy link
Contributor

Choose a reason for hiding this comment

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

remove this, while you're at it?

"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",
Copy link
Contributor

Choose a reason for hiding this comment

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

this feels a little silly to require as an external... but I guess it's consistent with dom4

Copy link
Contributor Author

Choose a reason for hiding this comment

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

yah i could easily be convinced to remove this line and bundle this one lib, but might as well be consistent

"tslib": "window",
Copy link
Contributor Author

Choose a reason for hiding this comment

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

i think this is the line that actually fixes #3262

Copy link
Contributor

Choose a reason for hiding this comment

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

how does this work? I see very little documentation about this "window" option

Copy link
Contributor Author

Choose a reason for hiding this comment

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

i had to dig through the tslib code to figure out what global it exposes. turns out it adds methods directly to window. same as dom4.

});

/**
Expand Down