Requirements

  • Node.js ^20.19.0 or >=22.12.0
  • Svelte 5, SvelteKit 2, and Vite 8
  • pnpm 10 is recommended; npm, Yarn, and Bun are also supported by the create command

Creating a project

Run the command for your package manager.

PNPM first

The repository and generated templates are tested with pnpm 10.

npm create @sveltepress@latest
sh
yarn create @sveltepress@latest
sh
pnpm create @sveltepress@latest
sh
bun create @sveltepress@latest
sh

Adding to an existing sveltekit project

Install vite plugin package

npm install --save @sveltepress/vite
sh
yarn add @sveltepress/vite
sh
pnpm install @sveltepress/vite
sh
bun add @sveltepress/vite
sh

Replace sveltekit plugin in vite.config.(js|ts)

vite.config.(js|ts)
-
+
-
+
import { function sveltekit(config?: KitConfig & Omit<Options, "onwarn"> & Pick<SvelteConfig, "vitePlugin">): Promise<Plugin[]>

Returns the SvelteKit Vite plugins. Since version 2.62.0 you can pass configuration directly, in which case svelte.config.js is ignored. Any options that don't belong to SvelteKit are passed through to vite-plugin-svelte.

sveltekit
} from '@sveltejs/kit/vite'
import { const sveltepress: (options?: SveltepressVitePluginOptions) => PluginOptionsveltepress } from '@sveltepress/vite' import { function defineConfig(config: UserConfig): UserConfig (+5 overloads)

Type helper to make it easier to use vite.config.ts accepts a direct

UserConfig

object, or a function that returns it. The function receives a

ConfigEnv

object.

defineConfig
} from 'vite'
const const config: UserConfigconfig = function defineConfig(config: UserConfig): UserConfig (+5 overloads)

Type helper to make it easier to use vite.config.ts accepts a direct

UserConfig

object, or a function that returns it. The function receives a

ConfigEnv

object.

defineConfig
({
UserConfig.plugins?: PluginOption[] | undefined

Array of vite plugins to use.

plugins
: [
function sveltekit(config?: KitConfig & Omit<Options, "onwarn"> & Pick<SvelteConfig, "vitePlugin">): Promise<Plugin[]>

Returns the SvelteKit Vite plugins. Since version 2.62.0 you can pass configuration directly, in which case svelte.config.js is ignored. Any options that don't belong to SvelteKit are passed through to vite-plugin-svelte.

sveltekit
(),
function sveltepress(options?: SveltepressVitePluginOptions): PluginOptionsveltepress(), ], }) export default const config: UserConfigconfig
ts
Remove the original sveltekit() plugin

sveltepress() already sets up SvelteKit for you. Keeping both sveltekit() and sveltepress() in plugins compiles every Svelte file twice and crashes the dev server with Expected token }.

Add '.md' extension to the extensions options in your svelte.config.js

svelte.config.js
-
+
import function adapter(options?: AdapterOptions): Adapteradapter from '@sveltejs/adapter-static'
import { function vitePreprocess(opts?: VitePreprocessOptions): PreprocessorGroupvitePreprocess } from '@sveltejs/vite-plugin-svelte'

/**
 * @type {import('@sveltejs/kit').Config}
 */
const 
const config: {
    extensions: string[];
    preprocess: PreprocessorGroup[];
    kit: {
        adapter: Adapter;
    };
}
@type{import('@sveltejs/kit').Config}
config
= {
extensions: string[]extensions: ['.svelte'], extensions: string[]extensions: ['.svelte', '.md'], // add .md here preprocess: PreprocessorGroup[]preprocess: [function vitePreprocess(opts?: VitePreprocessOptions): PreprocessorGroupvitePreprocess()],
kit: {
    adapter: Adapter;
}
kit
: {
adapter: Adapteradapter: function adapter(options?: AdapterOptions): Adapteradapter({ AdapterOptions.pages?: string | undefinedpages: 'dist', }), }, } export default
const config: {
    extensions: string[];
    preprocess: PreprocessorGroup[];
    kit: {
        adapter: Adapter;
    };
}
@type{import('@sveltejs/kit').Config}
config
ts
No svelte.config.js? (newer SvelteKit layout)

Projects scaffolded with a recent npx sv create keep their SvelteKit config inline in vite.config.ts and ship no svelte.config.js. Move those options into sveltepress({ svelteKitOptions }) (Sveltepress adds the '.md' extension for you automatically) and remove the standalone sveltekit() plugin:

vite.config.ts
import import adapteradapter from '@sveltejs/adapter-auto'
import { const sveltepress: (options?: SveltepressVitePluginOptions) => PluginOptionsveltepress } from '@sveltepress/vite'
import { function defineConfig(config: UserConfig): UserConfig (+5 overloads)

Type helper to make it easier to use vite.config.ts accepts a direct

UserConfig

object, or a function that returns it. The function receives a

ConfigEnv

object.

defineConfig
} from 'vite'
export default function defineConfig(config: UserConfig): UserConfig (+5 overloads)

Type helper to make it easier to use vite.config.ts accepts a direct

UserConfig

object, or a function that returns it. The function receives a

ConfigEnv

object.

defineConfig
({
UserConfig.plugins?: PluginOption[] | undefined

Array of vite plugins to use.

plugins
: [
function sveltepress(options?: SveltepressVitePluginOptions): PluginOptionsveltepress({ SveltepressVitePluginOptions.svelteKitOptions?: (KitConfig & Omit<Options, "onwarn"> & Pick<SvelteConfig, "vitePlugin">) | undefined

Options forwarded to the SvelteKit vite plugin that sveltepress() sets up internally.

Use this on the newer SvelteKit layout (no svelte.config.js, config passed inline to sveltekit()) to move your compilerOptions, adapter, etc. into sveltepress() and remove the standalone sveltekit() plugin. '.md' is always added to extensions automatically.

When omitted, SvelteKit reads its config from svelte.config.js as before.

svelteKitOptions
: {
compilerOptions?: Omit<CompileOptions, "filename" | "format" | "generate"> | undefined

The options to be passed to the Svelte compiler. A few options are set by default, including dev and css. However, some options are non-configurable, like filename, format, generate, and cssHash (in dev).

compilerOptions
: {
runes?: boolean | ((options: {
    filename: string;
}) => boolean | undefined) | undefined

Set to true to force the compiler into runes mode, even if there are no indications of runes usage. Set to false to force the compiler into ignoring runes, even if there are indications of runes usage. Set to undefined (the default) to infer runes mode from the component code. Is always true for JS/TS modules compiled with Svelte. Will be true by default in Svelte 6. Note that setting this to true in your svelte.config.js will force runes mode for your entire project, including components in node_modules, which is likely not what you want. If you're using Vite, consider using dynamicCompileOptions instead.

@defaultundefined
runes
: ({ filename: stringfilename }) =>
filename: stringfilename.
String.split(splitter: {
    [Symbol.split](string: string, limit?: number): string[];
}, limit?: number): string[] (+1 overload)

Split a string into substrings using the specified separator and return them as an array.

@paramsplitter An object that can split a string.@paramlimit A value used to limit the number of elements returned in the array.
split
(/[/\\]/).Array<string>.includes(searchElement: string, fromIndex?: number): boolean

Determines whether an array includes a certain element, returning true or false as appropriate.

@paramsearchElement The element to search for.@paramfromIndex The position in this array at which to begin searching for searchElement.
includes
('node_modules') ? var undefinedundefined : true,
}, KitConfig.adapter?: Adapter | undefined

Your adapter is run when executing vite build. It determines how the output is converted for different platforms.

@defaultundefined
adapter
: import adapteradapter(),
}, }), ], })
ts