Custom SvelteKit Server: dev + production with startup tasks

[stephane-klein]

Need to execute tasks at startup of your SvelteKit app? Here's a Proof of Concept of a SvelteKit Node custom server, which has the following characteristics:

• Allows launching a task, for example data model migration right at HTTP server startup
• Allows for example instantiating node-cron to execute scheduled tasks
• Both functionalities are available in development mode (npm run dev) as well as production mode (npm run build; npm run preview)

This allows me to create a Monolithic application.

Here's this POC: https://github.com/stephane-klein/poc-sveltekit-custom-server

I decided to share this project here because I thought it might be useful to some people, and also to ask you some questions at the end of this document.

To create this POC, I followed the official documentation SvelteKit Node custom server.

Here's what the custom_server src/server.js looks like (click here to see the complete file version). Here, I've broken down this file to comment on it:

import express from 'express';
import cron from 'node-cron';
import db, { migrate } from '@lib/server/db.js';

const isDev = process.env.ENV !== 'production';

Below, I can launch the data model migration right at service startup:

migrate();

And then, I instantiate node-cron to launch a task every hour:

cron.schedule(
    '0 * * * *',
    async () => {
        console.log('Start task...');
        console.log(db().query('SELECT * FROM posts'));
        console.log('Task executed');
    }
);

async function createServer() {
    const app = express();

    app.get('/healthcheck', (req, res) => {
        res.end('ok');
    });

The src/server.js file has two operating modes. The first is "dev" mode, which instantiates a Vite server:

    if (isDev) {
        const { createServer: createViteServer } = await import('vite');

        const vite = await createViteServer({
            server: { middlewareMode: true },
            appType: 'custom'
        });

        app.use(vite.middlewares);

This works like vanilla SvelteKit npm run dev, with auto-reload...

Then, here's the code that's executed in built mode (npm run build; npm run preview):

    } else {
        const { handler } = await import('./handler.js');
        app.use(handler);
    }

For the rest of the project, nothing special, it's a simple Express server:

    const PORT = process.env.PORT || (isDev ? 5173 : 3000);
    app.listen(
        PORT,
        () => {
            console.log(`Server started on http://localhost:${PORT} in ${isDev ? 'development' : 'production'} mode`);
        }
    );
}

createServer().catch(err => {
    console.error('Error while starting server:', err);
    process.exit(1);
});

The src/server.js file is copied to the /build/ folder when executing pnpm run build.

I tested the POC's proper functioning in a Docker container.

Difficulty Point

SvelteKit uses module aliases, such as $lib.
Problem: by default, these module aliases are not configured when executing node src/server.js.

To allow me to import modules from src/lib/server/* in src/server.js like:

import db, { migrate } from '@lib/server/db.js';

I used the esm-module-alias library.

This complicates the project a bit, I had to configure this in /package.json:

{
    "scripts": {
        "dev": "ENV=development node --loader esm-module-alias/loader --no-warnings src/server.js",
        "preview": "ENV=production node --loader esm-module-alias/loader --no-warnings build/server.js",
        
    // ...

    "aliases": {
        "@lib": "src/lib/"
    }
}

• adding --loader esm-module-alias/loader --no-warnings
• and the aliases section

And in /vite.config.js:

export default defineConfig({
    plugins: [sveltekit()],
    resolve: {
        alias: {
          '@lib': path.resolve('./src/lib')
        }
    }
});

• adding alias

This complicates the project slightly, but I find it quite acceptable.

Summary and Questions

For now, I haven't pushed the implementation of this POC very far, but so far, everything seems to work very well.

The Developer Experience remains very good, identical to a classic SvelteKit.

Questions:

• Have you ever used this technique?
• Do you identify an error in this POC? A risk?
• Have you found a simpler alternative to esm-module-alias or to automatically configure @lib/?
• Do you have another technique to launch actions at startup of your SvelteKit SSR projects?
• Do you have any suggestions for improving this POC?

Thanks in advance for your contributions.

This note is also available here in French with a little more context.

Crosspost: I also published this message on Reddit Svelte https://old.reddit.com/r/sveltejs/comments/1kxtz1u/custom_sveltekit_server_dev_production_with/?

[colecrouter]

Very cool. Have you checked out this hook? I think it does something similar.

[stephane-klein]

@colecrouter Thank you very much for this information.

I just discovered that this Hook init was introduced in SvelteKit version 2.10 in December 2024: https://github.com/sveltejs/kit/releases/tag/%40sveltejs%2Fkit%402.10.0

Unfortunately I searched for this feature from mid 2022 to mid 2024.

As a result of this discovery, I'm not going to use my Sveltekit Node Custom Server. Instead I will use this Hook init.

Thanks