mirror of
https://github.com/Sevichecc/Urara-Blog.git
synced 2025-05-04 01:19:30 +08:00
132 lines
5.6 KiB
Text
132 lines
5.6 KiB
Text
# @sveltejs/adapter-static
|
|
|
|
[Adapter](https://kit.svelte.dev/docs/adapters) for SvelteKit apps that prerenders your entire site as a collection of static files. If you'd like to prerender only some pages, you will need to use a different adapter together with [the `prerender` option](https://kit.svelte.dev/docs/page-options#prerender).
|
|
|
|
## Usage
|
|
|
|
Install with `npm i -D @sveltejs/adapter-static`, then add the adapter to your `svelte.config.js`:
|
|
|
|
```js
|
|
// svelte.config.js
|
|
import adapter from '@sveltejs/adapter-static';
|
|
|
|
export default {
|
|
kit: {
|
|
adapter: adapter({
|
|
// default options are shown. On some platforms
|
|
// these options are set automatically — see below
|
|
pages: 'build',
|
|
assets: 'build',
|
|
fallback: null,
|
|
precompress: false
|
|
}),
|
|
|
|
prerender: {
|
|
// This can be false if you're using a fallback (i.e. SPA mode)
|
|
default: true
|
|
}
|
|
}
|
|
};
|
|
```
|
|
|
|
> ⚠️ You must ensure SvelteKit's [`trailingSlash`](https://kit.svelte.dev/docs/configuration#trailingslash) option is set appropriately for your environment. If your host does not render `/a.html` upon receiving a request for `/a` then you will need to set `trailingSlash: 'always'` to create `/a/index.html` instead.
|
|
|
|
## Zero-config support
|
|
|
|
Some platforms have zero-config support (more to come in future):
|
|
|
|
- [Vercel](https://vercel.com)
|
|
|
|
On these platforms, you should omit the adapter options so that `adapter-static` can provide the optimal configuration:
|
|
|
|
```diff
|
|
export default {
|
|
kit: {
|
|
- adapter: adapter({...}),
|
|
+ adapter: adapter(),
|
|
|
|
prerender: {
|
|
default: true
|
|
}
|
|
}
|
|
};
|
|
```
|
|
|
|
## Options
|
|
|
|
### pages
|
|
|
|
The directory to write prerendered pages to. It defaults to `build`.
|
|
|
|
### assets
|
|
|
|
The directory to write static assets (the contents of `static`, plus client-side JS and CSS generated by SvelteKit) to. Ordinarily this should be the same as `pages`, and it will default to whatever the value of `pages` is, but in rare circumstances you might need to output pages and assets to separate locations.
|
|
|
|
### fallback
|
|
|
|
Specify a fallback page for SPA mode, e.g. `index.html` or `200.html` or `404.html`.
|
|
|
|
### precompress
|
|
|
|
If `true`, precompresses files with brotli and gzip. This will generate `.br` and `.gz` files.
|
|
|
|
## SPA mode
|
|
|
|
You can use `adapter-static` to create a single-page app or SPA by specifying a **fallback page**.
|
|
|
|
> In most situations this is not recommended: it harms SEO, tends to slow down perceived performance, and makes your app inaccessible to users if JavaScript fails or is disabled (which happens [more often than you probably think](https://kryogenix.org/code/browser/everyonehasjs.html)).
|
|
|
|
The fallback page is an HTML page created by SvelteKit that loads your app and navigates to the correct route. For example [Surge](https://surge.sh/help/adding-a-200-page-for-client-side-routing), a static web host, lets you add a `200.html` file that will handle any requests that don't correspond to static assets or prerendered pages. We can create that file like so:
|
|
|
|
```js
|
|
// svelte.config.js
|
|
import adapter from '@sveltejs/adapter-static';
|
|
|
|
export default {
|
|
kit: {
|
|
adapter: adapter({
|
|
fallback: '200.html'
|
|
})
|
|
}
|
|
};
|
|
```
|
|
|
|
When operating in SPA mode, you can omit `config.kit.prerender.default` (or set it to `false`, its default value), and only pages that have the [`prerender`](https://kit.svelte.dev/docs/page-options#prerender) option set will be prerendered at build time.
|
|
|
|
SvelteKit will still crawl your app's entry points looking for prerenderable pages. If `svelte-kit build` fails because of pages that can't be loaded outside the browser, you can set `config.kit.prerender.entries` to `[]` to prevent this from happening. (Setting `config.kit.prerender.enabled` also has this effect, but would prevent the fallback page from being generated.)
|
|
|
|
> ⚠️ During development, SvelteKit will still attempt to server-side render your routes. This means accessing things that are only available in the browser (such as the `window` object) will result in errors, even though this would be valid in the output app. To align the behavior of SvelteKit's dev mode with your SPA, you can [call `resolve()` with a parameter of `{ssr: false}` inside the `handle()` hook](https://kit.svelte.dev/docs/hooks#handle).
|
|
|
|
## GitHub Pages
|
|
|
|
When building for GitHub Pages, make sure to update [`paths.base`](https://kit.svelte.dev/docs/configuration#paths) to match your repo name, since the site will be served from <https://your-username.github.io/your-repo-name> rather than from the root.
|
|
|
|
You will have to prevent GitHub's provided Jekyll from managing your site by putting an empty `.nojekyll` file in your static folder. If you do not want to disable Jekyll, change the kit's `appDir` configuration option to `'app_'` or anything not starting with an underscore. For more information, see GitHub's [Jekyll documentation](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll#configuring-jekyll-in-your-github-pages-site).
|
|
|
|
A config for GitHub Pages might look like the following:
|
|
|
|
```js
|
|
const dev = process.env.NODE_ENV === 'development';
|
|
|
|
/** @type {import('@sveltejs/kit').Config} */
|
|
const config = {
|
|
...
|
|
kit: {
|
|
...
|
|
paths: {
|
|
base: dev ? '' : '/your-repo-name',
|
|
},
|
|
// If you are not using a .nojekyll file, change your appDir to something not starting with an underscore.
|
|
// For example, instead of '_app', use 'app_', 'internal', etc.
|
|
appDir: 'internal',
|
|
}
|
|
};
|
|
```
|
|
|
|
## Changelog
|
|
|
|
[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-static/CHANGELOG.md).
|
|
|
|
## License
|
|
|
|
[MIT](LICENSE)
|