Skip to content

Clarify that public/index.html is special #8288

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.

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
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
17 changes: 13 additions & 4 deletions docusaurus/docs/using-the-public-folder.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,14 @@ title: Using the Public Folder

## Changing the HTML

The `public` folder contains the HTML file so you can tweak it, for example, to [set the page title](title-and-meta-tags.md).
The `public` folder contains the `index.html` file so you can tweak it, for example to:

* [Set the page title](title-and-meta-tags.md).
* [Use environment variables](adding-custom-environment-variables.md).

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.
Expand All @@ -24,7 +29,11 @@ This mechanism provides a number of benefits:

However there is an **escape hatch** that you can use to add an asset outside of the module system.

If you put a file into the `public` folder, it will **not** be processed by Webpack. Instead it will be copied into the build folder untouched. To reference assets in the `public` folder, you need to use an environment variable called `PUBLIC_URL`.
If you put a file other than `index.html` into the `public` folder, it will **not** be processed by Webpack. Other files will be copied into the build folder untouched.

## Referencing Assets Outside of the Module System

To reference assets in the `public` folder, you need to use an environment variable called `PUBLIC_URL`.

Inside `index.html`, you can use it like this:

Expand All @@ -47,9 +56,9 @@ render() {
}
```

Keep in mind the downsides of this approach:
## Downsides of this approach

- None of the files in `public` folder get post-processed or minified.
- None of the files in `public` folder get post-processed (with the exception of `index.html`, as discussed above) or minified.
- 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.

Expand Down