Vercel SPA routing and resource loading: Solve deep URL access issues

This article aims to solve the problem of deep URL refresh or direct access causing page resource loading failure when deploying single page applications (SPAs) on Vercel. The core is to understand the difference between Vercel's routing rewriting mechanism and browser parsing relative paths. By configuring vercel.json to redirect all paths to index.html, and correct the reference method of static resources in HTML, change the relative path to absolute path, ensuring that the application can correctly load all resources under any URL.

1. Vercel Single Page Application (SPA) Routing Basics

The characteristic of a single page application (SPA) is that all routing switches are completed on the client side, and the server side actually only provides one entry file (usually index.html). When a user directly accesses the deep path of the application (such as /projects/home) in the browser or refreshes the page, the browser requests the URL from the server. Since the server does not have the actual file or directory of /projects/home, a mechanism is needed to direct all such requests to index.html, and the client routes to handle subsequent page renderings.

In Vercel, this is usually achieved through the rewrites (rewrite) rules in the vercel.json file. The most common SPA rewriting rules are as follows:

 {
  "trailingSlash": false,
  "rewrites": [
    { 
      "source": "/:path*", 
      "destination": "/index.html" 
    }
  ]
}

• "trailingSlash": false: This configuration item is used to control the behavior of the slash at the end of the URL. Setting to false means Vercel removes the slash at the end of the URL (for example, /about/ will be redirected to /about).
• "rewrites": Defines how the request path is rewritten.
  • "source": "/:path*": This is a wildcard pattern that matches any path. : Indicates the capture path segment, * Indicates matching zero or more characters. Therefore, it matches all incoming requests except static files.
  • "destination": "/index.html": Indicates that the matching request is rewrite to /index.html.

The meaning of this rule is: for any request that does not directly correspond to static files deployed by Vercel, it will be rewrite internally to index.html. In this way, whether it is accessing the root path /, first-level path /projects or deep path /projects/home, the server will return the content of index.html, and then the SPA's client route (such as React Router, Vue Router, History API, etc.) will take over and render the corresponding components.

2. The root cause of deep URL access and resource loading failure

Although the above vercel.json configuration looks perfectly to solve the SPA routing problem, in actual deployment, especially when accessing or refreshing deep URLs directly, you may encounter problems such as page style loss and script not executing. For example, when accessing kor.nz/projects/home, the page may not load the asset/style.css correctly.

This is not a vercel.json configuration error, but a result of the browser's mechanism to parse relative paths. When you reference a static resource in index.html, if you use a relative path, such as:

 <link rel="stylesheet" href="asset/style.css">
<script src="js/main.js"></script>
<img  src="/static/imghw/default1.png" data-src="images/logo.png" class="lazy" alt="Vercel SPA routing and resource loading: Solve deep URL access issues" >

The browser will parse these relative paths based on the URL of the current page.

• If the current URL is kor.nz/, the browser will try to load kor.nz/asset/style.css.
• If the current URL is kor.nz/projects, the browser will try to load kor.nz/projects/asset/style.css.
• If the current URL is kor.nz/projects/home, the browser will try to load kor.nz/projects/home/asset/style.css.

The problem is that your static resources (style.css, main.js, logo.png, etc.) are usually deployed in the root directory of the website (for example, public/asset/style.css is finally deployed to /asset/style.css). When the browser tries to request kor.nz/projects/home/asset/style.css, Vercel finds that there is no corresponding static file in this path. According to the rewrites rules we configured earlier, all unmatched paths will be rewritten to index.html. Therefore, the response received by the browser is not the content of style.css, but the content of index.html, causing the style to fail to load and the page to display exception.

3. Solution: Reference static resources using absolute paths

The key to solving this problem is to ensure that the browser correctly requests the server to the actual location of the static resource on the server, no matter which URL the user deeply accesses the page from. This can be done by changing the relative path of all static resources in HTML to an absolute path.

Before modification:

 <link rel="stylesheet" href="asset/style.css">
<script src="js/main.js"></script>
<img  src="/static/imghw/default1.png" data-src="images/logo.png" class="lazy" alt="Vercel SPA routing and resource loading: Solve deep URL access issues" >

After modification (add leading slash/):

 <link rel="stylesheet" href="/asset/style.css">
<script src="/js/main.js"></script>
<img  src="/static/imghw/default1.png" data-src="/images/logo.png" class="lazy" alt="Vercel SPA routing and resource loading: Solve deep URL access issues" >

By adding / before the path, you tell the browser that this is a path relative to the root of the website.

• Regardless of whether the current URL is kor.nz/, kor.nz/projects or kor.nz/projects/home, when the browser sees /asset/style.css, it always requests kor.nz/asset/style.css.
• Vercel prioritizes finding whether there is a matching static file when processing a request. If the asset/style.css does exist in the asset folder in the root directory of the deployment, Vercel will provide the file directly without triggering the rewrites rule.

This way, even if the deep URL is refreshed or directly accessed, the page can correctly load all required styles, scripts, and images, ensuring the SPA is running properly.

4. Complete vercel.json configuration examples and considerations

For most simple SPAs, the following vercel.json configuration combined with absolute path resource reference is perfectly sufficient:

 {
  "trailingSlash": false,
  "rewrites": [
    { 
      "source": "/:path*", 
      "destination": "/index.html" 
    }
  ]
}

Notes:

• Vercel's request processing priority: Vercel follows a certain priority when processing a request:
  1. Static file service: First try to match and directly provide the deployed static files (e.g. /asset/style.css).
  2. Redirects: If there is a matching redirection rule, redirection is performed.
  3. Rewrites: If the request is not a static file and there is no matching redirect, the rewrite rule is applied. It is precisely because static file services take precedence over rewriting that when the resource path is correct (absolute path), Vercel will serve the file directly without rewriting it to index.html.
• Development environment and production environment: When developing locally, the development server usually handles routing and resource loading, so this problem may not be immediately discovered. But after deploying to platforms such as Vercel, this problem will appear. Be sure to conduct adequate testing in the production environment.
• Build Tools: If you use modern front-end build tools (such as Webpack, Parcel, Vite, etc.), they usually provide configuration options to automatically process resource paths, such as configuring publicPath or base URLs to ensure that all resource references are the correct absolute paths. For simple Vanilla JS applications, manual inspection and modification are required.
• API routing and special paths: If your application contains Vercel Functions (Serverless Functions) or other special paths (such as /_next for Next.js applications), you may need more complex rewrites or routes configurations to exclude these paths, making sure they are not rewritten to index.html. For example:

   {
    "rewrites": [
      {
        "source": "/:path((?!api|_next).*)", // Exclude /api and /_next paths "destination": "/index.html"
      }
    ]
  }

  But for pure client SPAs, the above simple configuration is usually sufficient.

Summarize

There are two key points to deploying a single page application on Vercel and ensuring that deep URLs work properly:

1. Vercel configuration level: Use the rewrites rule of vercel.json to rewrite all non-static file requests to index.html to ensure that the server can always return the SPA's entry file.
2. HTML Resource Reference Level: When referencing all static resources (CSS, JavaScript, images, etc.) in index.html, be sure to use an absolute path (starting with /) to ensure that the browser can correctly request the actual location of these resources on the server regardless of the depth of the URL.

Understanding and correctly applying these two aspects can effectively solve the resource loading problems encountered by Vercel SPA during deep URL access.

The above is the detailed content of Vercel SPA routing and resource loading: Solve deep URL access issues. For more information, please follow other related articles on the PHP Chinese website!