FAQ

[benmccann]

Things I see a lot on Discord

• hmr questions - we should document the configuration
• load fallthrough
• vite aliases (also in jsconfig.json). can use this as a workaround to fix package imports. e.g. alias: { 'firebase/app': resolve('firebase/app/dist/index.cjs.js') }
• packages not working with vite (try moving between dependencies and devDependencies as in ReferenceError: require is not defined #655. or trying to include or exclude it in optimizeDeps)
• adapter broken because using old version (Remove 'Update latest tag on published packages' step #686 would be a better solution than documenting however)
• how do I use X with SvelteKit?
  • how do I setup Tailwind (pointing people to https://github.com/svelte-add/tailwindcss always works)
  • how do I setup a database? (put querying code in endpoints and not .svelte files. tips for database setup code and SvelteKit Process Hooks #693 (comment))
  • how do I use Axios (you probably don't need it. just use fetch instead. or if you insist you're probably better off using an ESM-friendly alternative like redaxios. finally, if you still want to use axios itself, try putting it in optimizeDeps.include)

[GrygrFlzr]

Some Vite issues related to the FAQ:

• Bundling SSR Modules using CommonJS exports alias results in ReferenceError: exports is not defined vitejs/vite#2579: Bundling SSR Modules using CommonJS exports alias results in ReferenceError: exports is not defined
  Relevant for dependencies like cookie - ugly workaround available but breaks in other places:

  import { createRequire } from "module";
  const require = createRequire(import.meta.url);
  const cookie = require("cookie");

• Import normalization resolves as out of root if path contains URL encoded characters vitejs/vite#2585: Import normalization resolves as out of root if path contains URL encoded characters
  Easy workaround by making sure path doesn't have spaces or other characters, until fix: handle paths with special characters in injectQuery (fix #2585) vitejs/vite#2614 is merged.
• Feature Request: option for publicDir to override the default public root in dev mode vitejs/vite#2587: Feature Request: option for publicDir to override the default public root in dev mode
  We need to mention to not accidentally use <img src="/static/image.png"> which works in dev but not in build.
• Changes to external css file or external ts file used in svelte file does not trigger reload with HMR vitejs/vite#2633: Changes to external css file or external ts file used in svelte file does not trigger reload with HMR
• Vite bundles wrong file from Zod vitejs/vite#2639: Vite bundles wrong file from Zod

[tylergannon]

Not sure how frequent the question is but it took me a while to discover that Vite's HMR websocket port is not 3000 as advertised, but 24678. Only once I knew that was I able to get my dev server working in a docker container.

services:
  web:
    image: "node:alpine"
    command: pnpm run dev
    ports: ["3000:3000", "24678:24678"]

[techniq]

Related to @tylergannon, I ran into an initial error on startup when using my dotnet backend to proxy the frontend to simplify CORS (https://localhost:5443 => ws://localhost:3001).

Adding the following to svelte.config.cjs fixed the issue for me (so it uses ws instead of wss and port 3001)

module.exports = {
  kit: {
    vite: {
      server: {
        hmr: {
          protocol: 'ws',
          port: 3001,
        },
      }
  }
}

• Vite docs

[rmunn]

I feel like a quick guide to Vite's dependency-related options would be a good thing to put in Svelte-Kit's FAQ. The Vite documentation does contain what you need to know, but for a newbie it can feel a bit confusing. Why is there different behavior between dependencies and devDependencies? What does optimizeDeps do, anyway? And what will happen if I specify ssr.external vs ssr.noExternal? What's this "externalizing" dependencies thing?

I've been doing Javascript for several years and I myself am not 100% clear on some of those questions, certainly not enough to be able to answer newbie questions. Someone new to Javascript is going to feel lost at sea with this stuff. Since Svelte-Kit comes configured with SSR out-of-the-box, I think something in the documentation should include a gentle guide to SSR, the difference between ESM and CJS modules, and what it all means, followed by some suggested troubleshooting steps if you run into the dreaded "require is not defined" error trying to import some NPM package. No need to go into too much detail since it's going to be a document intended for newbies, and you don't want to overwhelm them with too much information, but just something like "Javascript modules have two different formats, CJS that uses 'require' and ESM that uses 'import'. We try to hide the difference from you and make things Just Work™ as much as possible, but you'll occasionally run into trouble with NPM packages you're trying to import. When you do, here are some steps to try."

In other words, something like the "How do I fix the error I'm getting trying to include a package?" section in #877 but fleshed out a little more, with a couple sentences to explain the most basic of the concepts and a few different common scenarios: the error message you'll see, the solution that works for that scenario.

[GrygrFlzr]

Going to answer some of the questions raised so that it can go into the FAQ.

What does optimizeDeps do?

A lot of what I know about the Vite configs is actually guesswork - we unfortunately don't have a very good answer to this because I literally test it with trial and error. Generally the "algorithm" I use to start with is that I exclude ESM dependencies and include other types of dependencies, and then move it to the opposite if it doesn't work. Janky, I know.

Why is there different behavior between dependencies and devDependencies?

ssr.external and ssr.noExternal are clearer since they respectively exclude and include a dependency. So a dependency listed in ssr.noExternal would be bundled with the final output of the application, instead of importing from node_modules.

The difference between prod and dev is because we've explicitly added ssr.noExternal to the config and included all production dependencies that way. This is additionally confusing due to the common practice of having most Svelte dependencies in devDependencies as they are usually compiled away and not imported at runtime.

Javascript modules have two different formats

Unfortunately for us, it has way more: AMD, UMD, IIFE, etc. Which complicates the above configuration options even further, but CJS and ESM are the main two nowadays, yes.

the solution that works for that scenario

This should be okay - I can think of several common dependencies people have tried to use in the Discord, like carbon-components-svelte and axios (though for the latter I usually recommend node-fetch if possible or redaxios if they need an ESM version of it).

[benmccann]

@GrygrFlzr thanks for this. Not sure if you saw, but I have a PR pending for the FAQ. Let me know if you have any improvements you'd suggest there: #877. I hadn't mentioned anything about ssr.external / ssr.noExternal. Is that something that can also fix issues people encounter importing a library?

One thing I'm always wondering about is whether this is just how it will always be using Vite or if a portion of these issues are caused by shortcomings in Vite. I linked to vitejs/vite#2579 in the FAQ entry since that seems like a common one. I suspect that there are possibly others that I'm not aware of or that haven't been tracked down yet, but am not basing that off of much besides the fact that no one really understands how these options work which makes me think that's because there's issues preventing them from working consistently.

[benmccann]

The FAQ content has been merged into this repo, but still needs to be published: sveltejs/sites#19