Setting paths.base in svelte.config.js causes adapter-static to fail (404)

[janwillemtulp]

Describe the bug

adapter-static fails when I run npm run build and I have set paths.base to some path (as intended to eventually deploy on GitHub pages). The build process returns a 404 as it cannot find the appropriate routes or static resources.

Reproduction

I created an empty project to reproduce the behavior. I am using the adapter-static to build a production version of the site. I followed the steps from the ReadMe.

I have created 1 additional route: /a/index.svelte
In the root index /index.svelte I created a reference to this route:
<a href="/a" title="a link">a link</a>
as well as a reference to an image (the already present favicon):
<img alt="course-title" src="favicon.png" />

Commenting out either one of the produces the same error. The build process stops when the first error occurs, but it seems it is regardless of whether it's a route or static resource reference.

The error is:
404 /a (linked from /your-repo-name)
or
404 /favicon.png (linked from /your-repo-name)

In svelte.config.js I have set paths.base to /your-repo-name, basically a copy of the description in the ReadMe for adapter-static. Setting this paths.base to an empty string does not produce the error. Also setting prerender to false also doesn't produce the error, but obviously, that's not what I want here.

Logs

svelte.config.js

import adapter from '@sveltejs/adapter-static';

const dev = process.env.NODE_ENV === 'development';

/** @type {import('@sveltejs/kit').Config} */
const config = {
	kit: {
		// adapter: adapter()
		// adapter: firebase()
		adapter: adapter(),
		prerender: {
			default: true
		},
		paths: {
			base: dev ? '' : '/your-repo-name'
		},
		appDir: 'internal'
	}
};

package.json:

{
	"name": "test",
	"version": "0.0.1",
	"scripts": {
		"dev": "svelte-kit dev",
		"build": "svelte-kit build",
		"package": "svelte-kit package",
		"preview": "svelte-kit preview",
		"prepare": "svelte-kit sync",
		"lint": "prettier --ignore-path .gitignore --check --plugin-search-dir=. . && eslint --ignore-path .gitignore .",
		"format": "prettier --ignore-path .gitignore --write --plugin-search-dir=. ."
	},
	"devDependencies": {
		"@sveltejs/adapter-auto": "next",
		"@sveltejs/adapter-static": "^1.0.0-next.29",
		"@sveltejs/kit": "next",
		"eslint": "^7.32.0",
		"eslint-config-prettier": "^8.3.0",
		"eslint-plugin-svelte3": "^3.2.1",
		"gh-pages": "^3.2.3",
		"prettier": "^2.5.1",
		"prettier-plugin-svelte": "^2.5.0",
		"svelte": "^3.44.0",
		"svelte-adapter-firebase": "^0.13.1"
	},
	"type": "module"
}

System Info

System:
    OS: macOS 12.3.1
    CPU: (8) x64 Intel(R) Core(TM) i7-6700K CPU @ 4.00GHz
    Memory: 258.53 MB / 32.00 GB
    Shell: 5.8 - /bin/zsh
  Binaries:
    Node: 16.14.2 - ~/.nvm/versions/node/v16.14.2/bin/node
    npm: 8.5.0 - ~/.nvm/versions/node/v16.14.2/bin/npm
  Browsers:
    Chrome: 99.0.4844.84
    Edge: 100.0.1185.29
    Firefox: 95.0.2
    Safari: 15.4
  npmPackages:
    @sveltejs/adapter-auto: next => 1.0.0-next.34
    @sveltejs/adapter-static: ^1.0.0-next.29 => 1.0.0-next.29
    @sveltejs/kit: next => 1.0.0-next.306
    svelte: ^3.44.0 => 3.46.6

Severity

blocking an upgrade

Additional Information

No response

[russellsamora]

replicated - not sure if this is worth noting but right now my workaround is only using relative links (href="a") which builds fine, not root-relative (your example).

[janwillemtulp]

Oh really?

I just tried with
<a href="a" title="home">home</a>
as well as with
<img src="favicon.png" />

and both give the same error. In fact, the error for <a href="a" title="home">home</a> does contain the / in the error message itself 404 /a (linked from /your-repo-name) even though I use a relative path.

So, I can't reproduce your workaround unfortunately...

P.S. I also removed .svelte-kit to make sure no old files would affect the result

[kevin-chassagne]

Try with a config.kit.prerender.entries: []
It's working for me :)

[janwillemtulp]

Thanks, will do!!

[russellsamora]

just tried with the skeleton build and latest (kit v328 and static v30) and reproduced the 404. config.kit.prerender.entries: [] doesn't generate html files.

[ptrxyz]

I also ran into this bug, and had a quick discussion with @mrkishi who confirmed this being a bug. To replicate, simply create a new SvelteKit demo application, add adapter-static and set config.kit.paths.base to anything.
Run npm run build, you will run into a 404.

This is true for current versions:

		"@sveltejs/adapter-auto": "next",
		"@sveltejs/adapter-static": "^1.0.0-next.29",
		"@sveltejs/kit": "next",

[DougAnderson444]

works @sveltejs/adapter-static: 1.0.0-next.30 with "@sveltejs/kit": "1.0.0-next.327"
breaks @sveltejs/adapter-static: 1.0.0-next.30 with "@sveltejs/kit": "1.0.0-next.328"

Working repro: https://github.com/DougAnderson444/test-static-adapter-versions

Working combination:

  npmPackages:
    @sveltejs/adapter-static: 1.0.0-next.30
    @sveltejs/kit: next => 1.0.0-next.327
    svelte: ^3.44.0 => 3.46.6

Clone, build, then change to @sveltejs/kit: next => 1.0.0-next.328 to see it not generating an docs/index.html

[metonym]

@DougAnderson444 I believe that issue was fixed by #4928 in 1.0.0-next.331

[DougAnderson444]

@metonym you are right, .331 works!! Thanks! :)

[shot-codes]

I have this exact issue with the following configuration.

"@sveltejs/adapter-static": "^1.0.0-next.34",
"@sveltejs/kit": "next",
"svelte": "^3.44.0",

Build fails with 404 / (linked from /static/build/beds) and adding config.kit.prerender.entries: [] allows for building but doesn't generate html. This problem occurred suddenly and I had previously had success building with paths.base set.

[shot-codes]

I managed to find a workaround by importing base from $app/paths and prepending it to my hrefs:

<script>
  import { base } from '$app/paths';
</script>

<a href="{base}/">Home</a>
<a href="{base}/about">About</a>

[nikhil-advait]

Issue still occurs for ->

@sveltejs/kit@1.0.0-next.357
"@sveltejs/adapter-static": "^1.0.0-next.34"
"svelte": "^3.46.0",

[sonyarianto]

I managed to find a workaround by importing base from $app/paths and prepending it to my hrefs:

<script>
  import { base } from '$app/paths';
</script>

<a href="{base}/">Home</a>
<a href="{base}/about">About</a>

this save my life, the error during npm run build actually mention we should import $app/paths but with this sample post everything become clear :) thank you.

[dummdidumm]

The "workaround" shown above is the correct solution (and to not write it everytime, you could abstract it away into a component). There is no way to make this work as expected otherwise. Doing something like /foo is always relative to the root of the site, this is how the browser interprets this. We can't intercept this because with adapter-static there is no runtime on the server, and we can't assume that JS is always present to somehow reroute these links.

An alternative is to add a <base href="/your-base-path/" /> to the head of app.html. It would save you from needing to prepend the base everywhere, but you no longer can use relative links: <a href="foo">..</a> will always resolve to your-base-path/foo, no matter what page you are on and how many segments the url has.

I therefore switched the tag to "documentation" - we need to better document this, and the error message could probably get some more details or a link to the docs.

[Fyrgeit]

Hi, I'm having the same issue, and already figured out I had to append base from $app/paths to all my links.

However, the error doesn't point to a location in my code, so I'll never know if I miss one link or not. Any ideas?

[TobiasFG]

This was a odd one, but posting here in case others have the same issue.
(Specifically for those using the static adapter to deploy to GitHub Pages)
Perhaps @Fyrgeit

If you receive the following build error:

Error: 404 / does not begin with `base`, which is configured in `paths.base` and can be imported from `$app/paths` - see https://kit.svelte.dev/docs/configuration#paths for more info (linked from /volleydrills/)
To suppress or handle this error, implement `handleHttpError` in https://kit.svelte.dev/docs/configuration#prerender
    at file:///home/runner/work/volleydrills/volleydrills/node_modules/@sveltejs/kit/src/core/config/options.js:202:13
    at file:///home/runner/work/volleydrills/volleydrills/node_modules/@sveltejs/kit/src/core/postbuild/prerender.js:65:25
    at visit (file:///home/runner/work/volleydrills/volleydrills/node_modules/@sveltejs/kit/src/core/postbuild/prerender.js:195:4)
    at Object.fn (file:///home/runner/work/volleydrills/volleydrills/node_modules/@sveltejs/kit/src/core/postbuild/prerender.js:1[84](https://github.com/TobiasFG/volleydrills/actions/runs/10703175534/job/29673113472#step:6:85):22)
    at dequeue (file:///home/runner/work/volleydrills/volleydrills/node_modules/@sveltejs/kit/src/core/postbuild/queue.js:40:42)
    at file:///home/runner/work/volleydrills/volleydrills/node_modules/@sveltejs/kit/src/core/postbuild/queue.js:49:7
Emitted 'error' event on Worker instance at:
    at [kOnErrorMessage] (node:internal/worker:314:10)
    at [kOnMessage] (node:internal/worker:325:37)
    at MessagePort.<anonymous> (node:internal/worker:225:57)
    at [nodejs.internal.kHybridDispatch] (node:internal/event_target:7[86](https://github.com/TobiasFG/volleydrills/actions/runs/10703175534/job/29673113472#step:6:87):20)
    at exports.emitMessage (node:internal/per_context/messageport:23:28)
Node.js v18.20.4
error: script "build" exited with code 1

And have prefixed all links with base from $app/paths.

svelte.config.js:

import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
import adapter from '@sveltejs/adapter-static'

const dev = process.env.NODE_ENV === 'development'
/** @type {import('@sveltejs/kit').Config} */
const config = {
  preprocess: vitePreprocess(),
  kit: {
    adapter: adapter(),
    paths: {
      base: dev ? '' : '/your-repo-name',
    },
  },
}
export default config

The 404 / does not link to anything, unlike when I manually introduce a link not prefixed with base which will show as /some-link

Reason and pitfall here is that you somewhere have: "{base}/" which should be corrected to just "{base}"

For me at least, this was not easy to understand as the error code, while completely correct, does not point to anything in the codebase or include a warning that this can be cause by a link ending in /.

Edit
I can also highly recommend creating a utility/helper function:

import { base } from '$app/paths'

export const LinkHandler = (link: string) => {
  if (process.env.NODE_ENV === 'development') {
    return link
  }

  if (link === '/') {
    return base
  }

  return base + link
}

Which will allow you to abstract all this away and do: href={LinkHandler('/changelog')} throughout your app instead.
Feel free to educate me, if this is bad practice 😄

Hope this might help someone.