|
2 | 2 | title: Adding a Path Prefix |
3 | 3 | --- |
4 | 4 |
|
5 | | -Many sites are hosted at something other than the root of their domain. |
| 5 | +Many applications are hosted at something other than the root (`/`) of their domain. |
6 | 6 |
|
7 | | -E.g. a Gatsby blog could live at `example.com/blog/` or a site could be hosted |
8 | | -on GitHub Pages at `example.github.io/my-gatsby-site/` |
| 7 | +For example, a Gatsby blog could live at `example.com/blog/` or a site could be hosted on GitHub Pages at `example.github.io/my-gatsby-site/` |
9 | 8 |
|
10 | 9 | Each of these sites need a prefix added to all paths on the site. So a link to |
11 | 10 | `/my-sweet-blog-post/` should be rewritten to `/blog/my-sweet-blog-post`. |
12 | 11 |
|
13 | | -In addition links to various resources (JavaScript, images, CSS) need the same |
14 | | -prefix added (this is accomplished by setting the `publicPath` in webpack). |
| 12 | +In addition links to various resources (JavaScript, CSS, images, and other static content) need the same prefix, so that the site continues to function and display correctly, even if served from this path prefix. |
15 | 13 |
|
16 | | -Luckily, for most sites, this work can be offloaded to Gatsby. Using |
17 | | -[Gatsby's Link component](/docs/gatsby-link/) for internal links ensures those links |
18 | | -will be prefixed correctly. Gatsby ensures that paths created internally and by |
19 | | -webpack are also correctly prefixed. |
| 14 | +Let's get this functionality implemented. We'll add an option to our `gatsby-config.js`, and add a flag to our build command. |
20 | 15 |
|
21 | | -## Development |
| 16 | +### Add to `gatsby-config.js` |
22 | 17 |
|
23 | | -During development, write paths as if there was no path prefix e.g. for a blog |
24 | | -hosted at `example.com/blog`, don't add `/blog` to your links. The prefix will |
25 | | -be added when you build for deployment. |
26 | | - |
27 | | -## Production build |
28 | | - |
29 | | -There are two steps for building a site with path prefixes. |
30 | | - |
31 | | -First define the prefix in your site's `gatsby-config.js`. |
32 | | - |
33 | | -```javascript:title=gatsby-config.js |
| 18 | +```js:title=gatsby-config.js |
34 | 19 | module.exports = { |
35 | | - // Note: it must *not* have a trailing slash. |
36 | 20 | pathPrefix: `/blog`, |
37 | 21 | } |
38 | 22 | ``` |
39 | 23 |
|
40 | | -Then pass `--prefix-paths` cmd option to Gatsby. |
| 24 | +### Build |
| 25 | + |
| 26 | +Once the `pathPrefix` is specified in `gastby-config.js`, we are well on our way to a prefixed app. The final step is to build out your application with a flag `--prefix-paths`, like so: |
41 | 27 |
|
42 | 28 | ```shell |
43 | 29 | gatsby build --prefix-paths |
44 | 30 | ``` |
45 | 31 |
|
46 | | -NOTE: When running the command without the `--prefix-paths` flag, Gatsby ignores |
47 | | -your `pathPrefix`. |
| 32 | +If this flag is not passed, Gatsby will ignore your `pathPrefix` and build out your site as if it were hosted from the root domain. |
| 33 | + |
| 34 | +### In-app linking |
| 35 | + |
| 36 | +As a developer using this feature, it should be seamless. We provide APIs and libraries to make using this functionality a breeze. Specifically, the [`Link`](/docs/gatsby-link/) component has built-in functionality to handle path prefixing. |
| 37 | + |
| 38 | +For example, if we want to link to our `/page-2` link (but the actual link will be prefixed, e.g. `/blog/page-2`) we don't want to hard code this path prefix in all of our links. We have your back! By using the `Link` component, we will automatically prefix your paths for you. If you later migrate off of `pathPrefix` your links will _still_ work seamlessly. |
| 39 | + |
| 40 | +Let's look at a quick example. |
| 41 | + |
| 42 | +```jsx:title=src/pages/index.js |
| 43 | +import React from "react" |
| 44 | +import { Link } from "gatsby" |
| 45 | +import Layout from "../components/layout" |
| 46 | + |
| 47 | +function Index() { |
| 48 | + return ( |
| 49 | + <Layout> |
| 50 | + {/* highlight-next-line */} |
| 51 | + <Link to="page-2">Page 2</Link> |
| 52 | + </Layout> |
| 53 | + ) |
| 54 | +} |
| 55 | +``` |
| 56 | + |
| 57 | +Without doing _anything_ and merely using the `Link` component, this link will be prefixed with our specified `pathPrefix` in `gatsby-config.js`. Woo hoo! |
| 58 | + |
| 59 | +If we want to do programatic/dynamic navigation, totally possible too! We expose a `navigate` helper, and this too automatically handles path prefixing. |
| 60 | + |
| 61 | +```jsx:title=src/pages/index.js |
| 62 | +import React from "react" |
| 63 | +import { navigate } from "gatsby" |
| 64 | +import Layout from "../components/layout" |
| 65 | + |
| 66 | +export default function Index() { |
| 67 | + return ( |
| 68 | + <Layout> |
| 69 | + {/* Note: this is an intentionally contrived example, but you get the idea! */} |
| 70 | + {/* highlight-next-line */} |
| 71 | + <button onClick={() => navigate("/page-2")}> |
| 72 | + Go to page 2, dynamically |
| 73 | + </button> |
| 74 | + </Layout> |
| 75 | + ) |
| 76 | +} |
| 77 | +``` |
| 78 | + |
| 79 | +### Additional Considerations |
| 80 | + |
| 81 | +The [`assetPrefix`](/docs/asset-prefix/) feature can be thought of as semi-related to this feature. That feature allows your assets (non-HTML files, e.g. images, JavaScript, etc.) to be hosted on a separate domain, for example a CDN. |
| 82 | + |
| 83 | +This feature works seamlessly with `assetPrefix`. Build out your application with the `--prefix-paths` flag and you'll be well on your way to hosting an application with its assets hosted on a CDN, and its core functionality available behind a path prefix. |
0 commit comments