SvelteKit

SvelteKit is a full-stack web framework for Svelte, with support for static site generation, single-page applications, and server-side rendering on Clever Cloud.

Clever Cloud supports all three SvelteKit rendering modes. SSG (static site generation) and SPA (single-page application) both use @sveltejs/adapter-static and deploy to the Static runtime. SSR (server-side rendering) uses @sveltejs/adapter-node and deploys to the Node.js runtime.

SSG is the right choice for content-oriented sites where pages don’t change per visitor. SPA works well for dashboards and interactive tools where SEO is not a priority. SSR is best when pages must reflect real-time data or per-user state.

To follow this guide with a fresh project, scaffold a new SvelteKit application using the official CLI (you’ll need Node.js):

npx sv create mySvelteApp
cd mySvelteApp
npm install

npx sv create mySvelteApp
cd mySvelteApp
pnpm install

Deploy as a static site

Both SSG and SPA modes use @sveltejs/adapter-static and deploy to the Clever Cloud Static runtime. SSG prebuilds every route as a separate HTML file at build time. SPA ships a single HTML shell and handles all routing in the browser.

Static Site Generation

Install the adapter, then configure it in vite.config.ts:

npm i -D @sveltejs/adapter-static

// vite.config.ts
import adapter from '@sveltejs/adapter-static';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    sveltekit({
      adapter: adapter()
    })
  ]
});

Enable prerendering in your root layout so SvelteKit generates static HTML for every route at build time:

// src/routes/+layout.js
export const prerender = true;

Single-Page Application

For a SPA, disable server-side rendering in the root layout and configure a fallback page. The fallback is an HTML file the static server returns for any path that has no matching file, allowing SvelteKit’s client-side router to take over:

// src/routes/+layout.js
export const ssr = false;

// vite.config.ts
import adapter from '@sveltejs/adapter-static';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    sveltekit({
      adapter: adapter({ fallback: '200.html' })
    })
  ]
});

Deploy a static application

You can create an application in our Console or through Clever Tools. Install them with npm or any supported package manager:

# Install with npm or any supported method
npm i -g clever-tools

# Login to Clever Cloud and check it worked
clever login
clever profile

Go to the folder where you want to create your application, and run the following command:

cd myStaticApp
clever create -t static

# If the folder is not a git repository, initialize it:
git init

To deploy on Clever Cloud, your local folder need to be an initialized git repository linked to an application. If you already have an application on Clever Cloud and want to link it to the current local folder:

clever link your_app_name_or_ID

Environment variables

Clever Cloud’s static runtime does not auto-detect SvelteKit, so you need to configure the output directory and build command explicitly. CC_WEBROOT points to the build/ directory that the adapter generates. Clever Cloud installs dependencies automatically, but does not run the build. CC_PRE_BUILD_HOOK is what triggers npm run build and produces the output directory:

clever env set CC_WEBROOT "build"
clever env set CC_PRE_BUILD_HOOK "npm install && npm run build"

clever env set CC_NODE_BUILD_TOOL "pnpm"  # optional if pnpm-lock.yaml is committed
clever env set CC_WEBROOT "build"
clever env set CC_PRE_BUILD_HOOK "pnpm install && pnpm run build"

Scale your application

A pico instance is sufficient to serve a static site. Use a medium build instance (M) to provide enough memory for compiling your project:

clever scale --flavor pico
clever scale --build-flavor M

Push your code

Once you complete these steps, commit your content to the local repository and deploy it:

git add .
git commit -m "First deploy"
clever deploy  # or: git push clever main:master (find the git URL in your app's Information tab)
clever open

You can display your website’s URL or add a custom domain to it (you’ll need to configure DNS):

clever domain
clever domain add your.website.tld

404 page location

If you need to use a specific page for 404 errors, define its location with SERVER_ERROR_PAGE_404 environment variable from Static Web Server, used as default in static runtime. For example : SERVER_ERROR_PAGE_404=404.html.

Deploy with server-side rendering

SSR renders pages on each request using a Node.js server. Use @sveltejs/adapter-node, which outputs a self-contained server bundle to the build/ directory.

Configure the adapter

Install the adapter and update vite.config.ts:

npm i -D @sveltejs/adapter-node

// vite.config.ts
import adapter from '@sveltejs/adapter-node';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    sveltekit({
      adapter: adapter()
    })
  ]
});

Create a Node.js application

Install Clever Tools and create a Node.js application linked to your project folder:

npm i -g clever-tools
clever login

cd mySvelteApp
clever create -t node

# Or link an existing Clever Cloud application:
clever link your_app_name_or_ID

Environment variables

Configure instance sizing, then set the required variables. A medium build instance (M) provides enough memory to compile the project; an XS instance is sufficient to run the server:

clever scale --build-flavor M
clever scale --flavor XS

clever env set PORT 8080
clever env set PROTOCOL_HEADER "X-Forwarded-Proto"
clever env set HOST_HEADER "Host"
clever env set CC_NODE_DEV_DEPENDENCIES install
clever env set CC_POST_BUILD_HOOK "npm run build"
clever env set CC_RUN_COMMAND "node build"

clever env set PORT 8080
clever env set PROTOCOL_HEADER "X-Forwarded-Proto"
clever env set HOST_HEADER "Host"
clever env set CC_NODE_BUILD_TOOL "pnpm"  # optional if pnpm-lock.yaml is committed
clever env set CC_NODE_DEV_DEPENDENCIES install
clever env set CC_POST_BUILD_HOOK "pnpm run build"
clever env set CC_RUN_COMMAND "node build"

By default, Clever Cloud only installs production dependencies, so vite and @sveltejs/kit would be missing when the build runs (they’re dev dependencies). CC_NODE_DEV_DEPENDENCIES tells it to install development dependencies too, and CC_POST_BUILD_HOOK runs vite build once they’re installed, producing the build/ directory that node build requires.

PORT must be set to 8080. SvelteKit’s built server listens on port 3000 by default, but Clever Cloud requires all applications to be exposed on port 8080.

PROTOCOL_HEADER and HOST_HEADER tell SvelteKit which headers to read the request protocol and hostname from. Clever Cloud routes all traffic through a reverse proxy and forwards the original protocol via X-Forwarded-Proto. The origin is then reconstructed from each incoming request. This means the configuration works with the default cleverapps.io domain and with any custom domain you add later.

Push your code

Once you complete these steps, commit your project and deploy it:

git add .
git commit -m "First deploy"
clever deploy  # or: git push clever main:master (find the git URL in your app's Information tab)
clever open

You can display your application’s URL or add a custom domain (DNS configuration required):

clever domain
clever domain add your.website.tld

Learn more