Svelte Web Framework

Common errors

• Error: SvelteKit encountered an error while trying to build your project.

  cause This generic error often indicates a problem during the compilation process, such as syntax errors in Svelte components, incorrect build configuration, or missing dependencies.
  fix Check the console output for more specific error messages that appear before this line. Ensure all dependencies are installed (`npm install`), resolve any syntax errors in `.svelte` files, and verify your `vite.config.ts` or `svelte.config.js` if you have custom configurations.

• ReferenceError: $ is not defined

  cause This error occurs when attempting to use Svelte stores (e.g., `count = $count + 1`) without Svelte's auto-subscription mechanism properly set up, or outside of a compiled Svelte component context.
  fix Ensure you are using the store with the `$` prefix within a `.svelte` component file, or explicitly subscribe to the store using `.subscribe()` in regular JavaScript/TypeScript files.

• Hydration mismatch

  cause This error typically happens when server-side rendered (SSR) HTML doesn't perfectly match the HTML generated by the client-side Svelte application during hydration. Common causes include conditional rendering differences, incorrect handling of empty slots, or async content during SSR.
  fix Inspect the differences in the generated HTML between the server and client. Ensure server-side and client-side logic are consistent, especially for dynamic content. SvelteKit often provides more details in the console regarding the specific mismatch. Check for issues with `{@html ...}` blocks or conditional rendering during initial load.

• TypeError: Cannot assign to read only property 'propName' of object '[object Object]'

  cause In Svelte 5, component props are immutable by default. This error occurs if you try to directly modify a prop received by a child component.
  fix If a prop needs to be mutable within the child component, create a local `$state` variable and initialize it with the prop's value: `let count = $state(initialCount);` Then, modify `count` instead of `initialCount`. If the parent needs to update the child, use a callback function passed as a prop or leverage two-way binding (`bind:propName`).

• Error: Svelte components must be defined with `export default class ...` or `export function ...`

  cause This error indicates that a `.svelte` file is not properly exporting its component, often due to a missing `export default` for a class or function definition, or if a component is missing entirely.
  fix Ensure your `.svelte` component file has `export default class ComponentName { ... }` or `export function ComponentName(props) { ... }` (for Runes mode). If using a `<script>` block, ensure it's at the top level and correctly defines the component logic.

Warnings

• breaking Svelte 5 introduced 'Runes' as the new default reactivity model, significantly changing how state management (`$state`, `$effect`, `$derived`) and component logic work compared to Svelte 4's assignment-based reactivity. Migrating from Svelte 4 will require refactoring components to use the new API.
  Fix: Refer to the Svelte 5 documentation and migration guides to understand and adopt the 'Runes' API. Existing Svelte 4 code can be run in 'legacy' mode, but migrating is recommended for new features and long-term support.
• gotcha Svelte is a compiler, not a runtime library that you directly include in the browser. It requires a build step (e.g., using Vite, Rollup, or Webpack) to transform `.svelte` files into executable JavaScript.
  Fix: Ensure your project is set up with a Svelte-compatible build toolchain. SvelteKit (created with `npx sv create`) provides this out-of-the-box.
• gotcha The `npx sv create` command initializes a SvelteKit project, which is a full-stack framework built on Svelte, not a barebones Svelte application. While recommended, it includes routing, server-side rendering, and other features beyond a simple Svelte SPA.
  Fix: If you need a minimal Svelte setup without SvelteKit, you'll need to configure a build tool (like Vite with `@sveltejs/vite-plugin-svelte`) manually. However, SvelteKit is generally preferred for most applications.
• gotcha Direct DOM manipulation using `document.querySelector` or similar APIs within Svelte components should generally be avoided. Svelte efficiently manages the DOM based on your component's state.
  Fix: Utilize Svelte's reactive bindings, directives, and lifecycle functions (`onMount`, `onDestroy`) to interact with the DOM indirectly. If direct DOM access is necessary (e.g., for integrating third-party libraries), use `bind:this` on elements or query within `onMount` after the component is rendered.

Install

• npm install svelte npm
• yarn add svelte yarn
• pnpm add svelte pnpm

Imports

• onMount

  import { onMount } from 'svelte';

  ESM-only since Svelte v4, requires a build step.
• tweened

  import { tweened } from 'svelte/motion';

• writable

  import { writable } from 'svelte/store';

Quickstart

This command creates a new SvelteKit project, the recommended way to build applications with Svelte. It sets up a development server and includes a basic Svelte application structure.

npx sv create my-app
cd my-app
npm install
npm run dev