Svelte

The magical disappearing UI framework.

• Read the introductory blog post
• Read the guide
• Try it out
• Chat on Discord

Tooling

This is the Svelte compiler, which is primarily intended for authors of tooling that integrates Svelte with different build systems. If you just want to write Svelte components and use them in your app, you probably want one of those tools:

Build Systems

• gulp-svelte - gulp plugin
• metalsmith-svelte - Metalsmith plugin
• system-svelte – System.js loader
• svelte-loader – Webpack loader
• meteor-svelte – Meteor build plugin
• sveltejs-brunch – Brunch build plugin
• rollup-plugin-svelte – Rollup plugin
• parcel-plugin-svelte - Parcel build plugin
• sveltify - Browserify transform

CSS Preprocessors

• Less
• modular-css
• PostCSS
• Sass

Additional tools

• svelte-dev-store - Use Redux tools to visualise Svelte store
• More to come!

Example usage

import * as svelte from 'svelte';

const { js, css, ast } = svelte.compile(source, {
	// the target module format – defaults to 'es' (ES2015 modules), can
	// also be 'amd', 'cjs', 'umd', 'iife' or 'eval'
	format: 'umd',

	// the filename of the source file, used in e.g. generating sourcemaps
	filename: 'MyComponent.html',

	// the name of the constructor. Required for 'iife' and 'umd' output,
	// but otherwise mostly useful for debugging. Defaults to 'SvelteComponent'
	name: 'MyComponent',

	// for 'amd' and 'umd' output, you can optionally specify an AMD module ID
	amd: {
		id: 'my-component'
	},

	// custom error/warning handlers. By default, errors will throw, and
	// warnings will be printed to the console. Where applicable, the
	// error/warning object will have `pos`, `loc` and `frame` properties
	onerror: err => {
		console.error( err.message );
	},

	onwarn: warning => {
		console.warn( warning.message );
	}
});

API

The Svelte compiler exposes the following API:

• compile(source [, options]) => { js, css, ast } - Compile the component with the given options (see below). Returns an object containing the compiled JavaScript, a sourcemap, an AST and transformed CSS.
• create(source [, options]) => function - Compile the component and return the component itself.
• preprocess(source, options) => Promise — Preprocess a source file, e.g. to use PostCSS or CoffeeScript
• VERSION - The version of this copy of the Svelte compiler as a string, 'x.x.x'.

Compiler options

The Svelte compiler optionally takes a second argument, an object of configuration options:

Preprocessor options

svelte.preprocess returns a Promise that resolves to an object with a toString method (other properties will be added in future). It takes an options object with markup, style or script properties:

const processed = await svelte.preprocess(source, {
	markup: ({ content }) => {
		// `content` is the entire component string
		return { code: '...', map: {...} };
	},

	style: ({ content, attributes }) => {
		// `content` is what's inside the <style> element, if present
		// `attributes` is a map of attributes on the element
		if (attributes.type !== 'text/scss') return;
		return { code: '...', map: {...} };
	},

	script: ({ content, attributes }) => {
		// `content` is what's inside the <script> element, if present
		// `attributes` is a map of attributes on the element
		if (attributes.type !== 'text/coffeescript') return;
		return { code: '...', map: {...} };
	}
});

The style and script preprocessors will run after the markup preprocessor. Each preprocessor can return a) nothing (in which case no transformation takes place), b) a { code, map } object, or c) a Promise that resolves to a) or b). Note that sourcemaps are currently discarded, but will be used in future versions of Svelte.

Example/starter repos

• sveltejs/template — the 'official' starter template
• sveltejs/template-webpack — using webpack for bundling
• charpeni/svelte-example - Some Svelte examples with configured Rollup, Babel, ESLint, directives, Two-Way binding, and nested components
• EmilTholin/svelte-test
• lukechinworth/codenames – example integration with Redux
• khtdr/svelte-redux-shopping-cart – Redux Shopping Cart example (with devtools and hot-reloading)

Development

Pull requests are encouraged and always welcome. Pick an issue and help us out!

To install and work on Svelte locally:

git clone [email protected]:sveltejs/svelte.git
cd svelte
npm install
npm run dev

The compiler is written in TypeScript, but don't let that put you off — it's basically just JavaScript with type annotations. You'll pick it up in no time. If you're using an editor other than VSCode you may need to install a plugin in order to get syntax highlighting and code hints etc.

Linking to a Live Project

You can make changes locally to Svelte and test it against any Svelte project. You can also use a default template for development. Instruction on setup are found in that project repository.

From your project:

cd ~/path/to/your-svelte-project
npm install ~/path/to/svelte

And you should be good to test changes locally.

To undo this and link to the official latest Svelte release, just run:

npm install svelte@latest

Running Tests

npm run test

For running single tests, you can use pattern matching:

npm run test -- -g "includes AST in svelte.compile output"

Alternately, you can add solo: true to any given test/../_config.js file, but remember never to commit that setting.

License

MIT