getting-started.md

Getting Started

• 1. Installation
• 2. Adding svelte-preprocess to our build workflow
• 3. Configuring preprocessors
  • 3.1 Prepending content

Note: The examples below are going to be using a hypothetical rollup.config.js as if we were configuring a simple Svelte application, but svelte-preprocess can be used in various setups. See "Usage".

1. Installation

First things first, let's create a new Svelte app project and add svelte-preprocess.

$ npx degit sveltejs/template my-svelte-app
$ cd my-svelte-app
$ npm install -D svelte-preprocess

svelte-preprocess doesn't have any language-specific dependency, so it's up to us to install the rest of tools we are going to use:

• Babel: npm install -D @babel/core @babel/preset-...
• CoffeeScript: npm install -D coffeescript
• TypeScript: npm install -D typescript
• PostCSS: npm install -D postcss postcss-load-config
• SugarSS: npm install -D postcss sugarss
• Less: npm install -D less
• Sass: npm install -D sass
• Pug: npm install -D pug
• Stylus: npm install -D stylus

For now, let's just install the main library.

2. Adding svelte-preprocess to our build workflow

Let's use svelte-preprocess in auto-preprocessing mode and add it to our rollup.config.js:

import svelte from 'rollup-plugin-svelte'
+ import { sveltePreprocess } from 'svelte-preprocess';

const production = !process.env.ROLLUP_WATCH

export default {
  input: 'src/main.js',
  output: {
    sourcemap: true,
    format: 'iife',
    name: 'app',
    file: 'public/bundle.js',
  },
  plugins: [
    svelte({
+      preprocess: sveltePreprocess(),
      // enable run-time checks when not in production
      dev: !production,
      // we'll extract any component CSS out into
      // a separate file — better for performance
      css: css => {
        css.write('public/bundle.css')
      },
    }),
  ],
}

Now our app's code can be written in any of the syntaxes supported by svelte-preprocess: Sass, Stylus, Less, CoffeeScript, TypeScript, Pug, PostCSS, Babel.

Note: If you use VS Code, check its usage guide to make the Svelte VS Code extension understand the content of your components.

3. Configuring preprocessors

Now let's assume our app markup is going to be written in Pug, our scripts in TypeScript, and our styles in Sass. We also want our styles to be auto-prefixed, so we're also going to need PostCSS. Let's install these dependencies:

Important: svelte-preprocess only handles content passed to it by svelte-loader, rollup-plugin-svelte and similar tools. If our TypeScript component import a TypeScript file, the bundler will be the one responsible for handling it. We must make sure it knows how to handle it!

$ npm i -D typescript sass postcss autoprefixer pug @rollup/plugin-typescript

After the installation is complete, we still need to configure our PostCSS options and add @rollup/plugin-typescript to our config.

import svelte from 'rollup-plugin-svelte'
import { sveltePreprocess } from 'svelte-preprocess';
+ import typescript from '@rollup/plugin-typescript';

const production = !process.env.ROLLUP_WATCH

export default {
  input: 'src/main.js',
  output: {
    sourcemap: true,
    format: 'iife',
    name: 'app',
    file: 'public/bundle.js',
  },
  plugins: [
+    // teach rollup how to handle typescript imports
+    typescript({ sourceMap: !production }),
    svelte({
+      preprocess: sveltePreprocess({
+         sourceMap: !production,
+         postcss: {
+           plugins: [require('autoprefixer')()]
+         }
+      }),
      // enable run-time checks when not in production
      dev: !production,
      // we'll extract any component CSS out into
      // a separate file — better for performance
      css: css => {
        css.write('public/bundle.css')
      },
    }),
  ],
}

And we're done! Our components can now be written as:

<template lang="pug"> h1 {name} </template>

<script lang="ts">
  export let name: string = 'world';
</script>

<style lang="scss">
  h1 {
    color: red;
  }
</style>

3.1 Prepending content

Now we're in need of a SCSS file to hold some variables. Let's assume it's created at src/styles/variables.scss.

// src/styles/variables.scss
$primary-color: red;

As in any SCSS project, we could just @use './path/to/variables.scss, but that can also become boring. svelte-preprocess accepts a prependData for almost every processor. Let's use it to prepend our import!

import svelte from 'rollup-plugin-svelte'
import { sveltePreprocess } from 'svelte-preprocess';

export default {
  input: 'src/main.js',
  output: {
    sourcemap: true,
    format: 'iife',
    name: 'app',
    file: 'public/bundle.js',
  },
  plugins: [
    svelte({
      preprocess: sveltePreprocess({
         sourceMap: !production,
+        scss: {
+          // We can use a path relative to the root because
+          // svelte-preprocess automatically adds it to `includePaths`
+          // if none is defined.
+          prependData: `@import 'src/styles/variables.scss';`
+        },
         postcss: {
           plugins: [require('autoprefixer')()]
         }
      }),
      // enable run-time checks when not in production
      dev: !production,
      // we'll extract any component CSS out into
      // a separate file — better for performance
      css: css => {
        css.write('public/bundle.css')
      },
    }),
  ],
}

Voila! We can now reference a variable from our file without having to explicitly import it.

<template lang="pug"> h1 {name} </template>

<script lang="ts">
  export let name: string = 'world';
</script>

<style lang="scss">
  h1 {
    color: $primary-color;
  }
</style>