SvelteKit Build Fails: Better Auth Error

Hey guys! So, you've been working hard on your SvelteKit project, feeling all the vibes, and then BAM! You hit that dreaded build step, run npm run build, and then try to start your server with node build. Instead of smooth sailing, you're smacked with a TypeError: msExports.ms is not a function. What in the actual Svelte-y heck is going on?

This is a super common frustration when integrating third-party authentication libraries like Better Auth into your SvelteKit application. You follow the docs, everything looks good in development, but as soon as you try to build for production, things go sideways. Don't sweat it, though! We're gonna dive deep into this specific error, figure out why it's happening, and get your SvelteKit app back up and running like a charm.

Understanding the "msExports.ms is not a function" Error

Alright, let's break down this cryptic error message: TypeError: msExports.ms is not a function. When your SvelteKit app crashes like this after a build, it usually points to an issue with how dependencies are being handled or how certain functions are being accessed in the production environment versus development.

In this specific case, the error is originating from the better-auth library, specifically within the getCookies function, which is called during the initialization of the authentication context. The line of code causing the fuss is const sessionToken = createCookie("session_token", { maxAge: options.session?.expiresIn || msExports.ms("7d") / 1e3 });. The key part here is msExports.ms. The error message tells us that msExports.ms isn't a function, which means the ms module, a tiny utility for converting milliseconds to human-readable strings (like '7d' for 7 days), isn't being loaded or accessed correctly after the build.

Why does this happen?

During development, your SvelteKit server often uses a more lenient module resolution system. Things might be imported dynamically or resolved in a way that works fine. However, when you run npm run build, SvelteKit and its adapters (like @sveltejs/adapter-node) perform a more rigorous bundling and tree-shaking process. This process can sometimes strip out or misplace modules that aren't explicitly declared as dependencies in the right places, or if they're imported in a way that the bundler doesn't recognize as essential for the production output.

The ms module is likely a peer dependency or an indirect dependency of better-auth. When the build process happens, if ms isn't correctly bundled or made available to the hooks.server.js file (where this error is occurring), then msExports.ms will indeed be undefined or not a function, leading to the crash.

The SvelteKit Build Process

It's crucial to understand that npm run build compiles your SvelteKit application into a production-ready format. This involves:

• Transpilation: Converting your modern JavaScript/TypeScript into a version compatible with your target environments.
• Bundling: Combining your code and dependencies into optimized files.
• Tree-shaking: Removing unused code to reduce the final bundle size.
• Adapting: Using an adapter (like @sveltejs/adapter-node) to package your application for a specific deployment target (e.g., a Node.js server).

Any hiccup in this process, especially with how dependencies are resolved and included, can lead to runtime errors like the one you're seeing. The fact that it works in development but fails after build is a classic sign of a build-time dependency issue.

Troubleshooting Steps

Before we dive into the fix, it's good practice to ensure you've followed the setup precisely. Sometimes, a small oversight can cause these headaches. We'll cover the specific fix shortly, but keep this process in mind: development success != production success. Always test your builds!

So, if you're seeing this error, take a deep breath. It's a solvable problem, and understanding the underlying cause is half the battle. Let's move on to figuring out exactly what needs to be done to get your ms module singing in harmony with better-auth after your SvelteKit build.

Why Your SvelteKit Build is Crashing with Better Auth

Alright, guys, let's get down to the nitty-gritty of why this TypeError: msExports.ms is not a function is messing with your SvelteKit build. We've established that it's a dependency issue, but let's pinpoint the exact culprit and how it relates to better-auth and SvelteKit's build process. The core problem lies in how the ms package, which better-auth relies on for handling time durations (like 7d for 7 days), is being bundled or made available when you run npm run build.

The ms Package: A Tiny But Mighty Dependency

The ms package is a super lightweight utility used to parse string durations like '100ms', '2 days', '3h', '7d', and convert them into milliseconds. better-auth uses this to set session expiration times. For example, ms("7d") converts the string "7d" into the number of milliseconds in 7 days. This is a common and efficient way to handle time configurations.

How Build Tools Can Break Things

When you run npm run build in a SvelteKit project, especially when using an adapter like @sveltejs/adapter-node, the build tool (Rollup or Vite, depending on your SvelteKit version and configuration) tries to bundle all your code and its dependencies into an optimized output. This process is designed to be efficient, but it can sometimes be too aggressive.

Here's what might be happening:

1. Incorrect Dependency Declaration: The ms package might be listed as a dependency in package.json instead of a devDependency or vice-versa, or it might not be listed at all if it's an indirect dependency that the bundler missed.
2. Bundling Exclusion: The build tool might decide that ms is not directly imported in your main application code and therefore exclude it from the final bundle, even though better-auth needs it internally.
3. Module Resolution Differences: Development environments often have more flexibility in how they resolve modules compared to the strict bundling performed for production builds. What works magically during npm run dev might not translate directly to the bundled output.

In the context of better-auth and sveltekit-cookies, the sveltekitCookies plugin is specifically designed to integrate with SvelteKit's server-side hooks (hooks.server.js). When better-auth tries to create cookies with session expiration times using the ms module, and that module isn't correctly included in the build output accessible by hooks.server.js, you get that TypeError. The msExports object is created, but the ms function property within it is missing.

The Role of @sveltejs/adapter-node

The @sveltejs/adapter-node specifically packages your SvelteKit app into a standalone Node.js server. This means everything needs to be self-contained within the build directory. If the ms package isn't properly included in this self-contained package, the Node.js server won't be able to find it at runtime, leading to the crash.

Why Your Setup is Causing This

Looking at your setup, you've correctly added better-auth and sveltekit-cookies. The configuration seems standard. The issue arises during the npm run build step, where the build tooling might not be recognizing the ms dependency as essential for the final bundled code of hooks.server.js.

Common Pitfalls and Solutions

Often, issues like this are resolved by ensuring that all necessary packages, including peer dependencies and indirectly required ones, are explicitly listed in your package.json and that the build tool understands their usage. Sometimes, a simple npm install after ensuring the correct dependencies are listed can resolve it.

Let's dive into the specific fix that addresses this common SvelteKit build problem with Better Auth.

The Fix: Ensuring the ms Dependency is Bundled

Alright team, we've diagnosed the problem: your SvelteKit app is throwing a TypeError: msExports.ms is not a function after build because the ms utility, which better-auth uses for time conversions, isn't being correctly included in the production build. This is a classic dependency resolution issue that SvelteKit's build process can sometimes run into, especially with third-party libraries.

The Solution: Explicitly Add ms as a Dependency

The most straightforward and effective fix is to explicitly tell your project that ms is a necessary dependency. Even though better-auth uses ms, the SvelteKit build tools (like Vite or Rollup) might not always automatically include it in the final bundle if it's not directly imported in your main app files. By adding it directly to your package.json, you ensure that the build process recognizes its importance.

Here's what you need to do:

1. Open your package.json file.
2. Locate the dependencies section. If you don't have one, create it.
3. Add "ms": "^2.1.2" (or the latest compatible version) to the dependencies list.

Your dependencies section in package.json might look something like this after the addition:

{
  "name": "your-sveltekit-project",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
    "preview": "vite preview",
    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json"
  },
  "devDependencies": {
    "@sveltejs/adapter-node": "^3.0.1", // Example version
    "@sveltejs/kit": "^2.0.0", // Example version
    "@sveltejs/vite-plugin-svelte": "^2.0.0", // Example version
    "svelte": "^3.0.0", // Example version
    "svelte-check": "^3.0.0", // Example version
    "typescript": "^5.0.0", // Example version
    "vite": "^4.0.0" // Example version
  },
  "dependencies": {
    "better-auth": "^1.4.5", // Your installed version
    "pg": "^8.16.3", // Your installed version
    "ms": "^2.1.2" // <-- ADD THIS LINE
  }
}

Important Note: Make sure you are adding it to dependencies, not devDependencies. devDependencies are typically only included during development and build time, but ms is needed at runtime by the better-auth library when your Node.js server is running.

4. Save your package.json file.
5. Run npm install to make sure npm picks up the new dependency and installs it correctly.
6. Re-run the build and start commands:

   npm run build
   node build
   

Why This Works

By adding ms to your dependencies, you are explicitly telling npm (and subsequently, SvelteKit's build tools) that this package is required for your application to run in production. The build process will now ensure that the ms module is included in the final bundled output that @sveltejs/adapter-node creates. When your Node.js server starts, it will be able to find and execute the ms function, resolving the TypeError.

Troubleshooting Further Issues

If you've added ms to your dependencies and still encounter issues, here are a few more things to check:

• Version Compatibility: Ensure the version of ms you've added is compatible with better-auth. Usually, the latest minor version is safe, but if you encounter new problems, you might need to check better-auth's documentation or issues for recommended ms versions.
• Clean Build: Sometimes, stale build artifacts can cause problems. Try deleting your build folder and node_modules folder, then run npm install again, followed by npm run build.
• Adapter Configuration: Double-check the configuration for @sveltejs/adapter-node in your svelte.config.js. While less likely to be the cause here, ensuring it's set up correctly is always a good idea.
• better-auth Configuration: Review your better-auth setup in hooks.server.js. Make sure the sveltekitCookies plugin is correctly placed and that your database connection is solid.

Conclusion

This TypeError: msExports.ms is not a function is a common hurdle when integrating libraries that have specific runtime dependencies. By explicitly adding ms to your dependencies in package.json and running npm install, you provide the build tool with the information it needs to bundle the necessary module. This simple step should get your SvelteKit app running smoothly after the build, allowing you to deploy your authentication system with confidence. Happy coding, guys!