Skip to content

Commit

Permalink
Clarify when to use the public folder
Browse files Browse the repository at this point in the history
  • Loading branch information
gaearon authored Dec 12, 2016
1 parent 587b2f8 commit ab3913c
Showing 1 changed file with 24 additions and 2 deletions.
26 changes: 24 additions & 2 deletions packages/react-scripts/template/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,9 @@ You can find the most recent version of this guide [here](https://github.com/fac
- [Post-Processing CSS](#post-processing-css)
- [Adding Images and Fonts](#adding-images-and-fonts)
- [Using the `public` Folder](#using-the-public-folder)
- [Changing the HTML](#changing-the-html)
- [Adding Assets Outside of the Module System](#adding-assets-outside-of-the-module-system)
- [When to Use the `public` Folder](#when-to-use-the-public-folder)
- [Using Global Variables](#using-global-variables)
- [Adding Bootstrap](#adding-bootstrap)
- [Adding Flow](#adding-flow)
Expand Down Expand Up @@ -372,7 +375,18 @@ An alternative way of handling static assets is described in the next section.

>Note: this feature is available with `[email protected]` and higher.
Normally we encourage you to `import` assets in JavaScript files as described above. This mechanism provides a number of benefits:
### Changing the HTML

The `public` folder contains the HTML file so you can tweak it, for example, to [set the page title](#changing-the-page-title).
The `<script>` tag with the compiled code will be added to it automatically during the build process.

### Adding Assets Outside of the Module System

You can also add other assets to the `public` folder.

Note that we normally we encourage you to `import` assets in JavaScript files instead.
For example, see the sections on [adding a stylesheet](#adding-a-stylesheet) and [adding images and fonts](#adding-images-and-fonts).
This mechanism provides a number of benefits:

* Scripts and stylesheets get minified and bundled together to avoid extra network requests.
* Missing files cause compilation errors instead of 404 errors for your users.
Expand Down Expand Up @@ -409,7 +423,15 @@ Keep in mind the downsides of this approach:
* Missing files will not be called at compilation time, and will cause 404 errors for your users.
* Result filenames won’t include content hashes so you’ll need to add query arguments or rename them every time they change.

However, it can be handy for referencing assets like [`manifest.webmanifest`](https://developer.mozilla.org/en-US/docs/Web/Manifest) from HTML, or including small scripts like [`pace.js`](http://github.hubspot.com/pace/docs/welcome/) outside of the bundled code.
### When to Use the `public` Folder

Normally we recommend importing [stylesheets](#adding-a-stylesheet), [images, and fonts](#adding-images-and-fonts) from JavaScript.
The `public` folder is useful as a workaround for a number of less common cases:

* You need a file with a specific name in the build output, such as [`manifest.webmanifest`](https://developer.mozilla.org/en-US/docs/Web/Manifest).
* You have thousands of images and need to dynamically reference their paths.
* You want to include a small script like [`pace.js`](http://github.hubspot.com/pace/docs/welcome/) outside of the bundled code.
* Some library may be incompatible with Webpack and you have no other option but to include it as a `<script>` tag.

Note that if you add a `<script>` that declares global variables, you also need to read the next section on using them.

Expand Down

0 comments on commit ab3913c

Please sign in to comment.