diff --git a/README.md b/README.md index cb559c5929..6dd84b18a9 100644 --- a/README.md +++ b/README.md @@ -1,151 +1,16 @@ -# Svelte +
+ + + +
-The magical disappearing UI framework. -* [Read the introductory blog post](https://svelte.technology/blog/frameworks-without-the-framework) -* [Read the guide](https://svelte.technology/guide) -* [Try it out](https://svelte.technology/repl) -* [Chat on Discord](https://discord.gg/yy75DKs) +## What is Svelte? ---- +Svelte is a new way to build web applications. It's a compiler that takes your declarative components and converts them into efficient JavaScript that surgically updates the DOM. -## Tooling +Learn more at the [Svelte website](https://svelte.dev), or stop by the [Discord chatroom](https://discord.gg/yy75DKs). -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](https://github.com/shinnn/gulp-svelte) - gulp plugin -* [metalsmith-svelte](https://github.com/shinnn/metalsmith-svelte) - Metalsmith plugin -* [system-svelte](https://github.com/CanopyTax/system-svelte) – System.js loader -* [svelte-loader](https://github.com/sveltejs/svelte-loader) – Webpack loader -* [meteor-svelte](https://github.com/klaussner/meteor-svelte) – Meteor build plugin -* [sveltejs-brunch](https://github.com/StarpTech/sveltejs-brunch) – Brunch build plugin -* [rollup-plugin-svelte](https://github.com/rollup/rollup-plugin-svelte) – Rollup plugin -* [parcel-plugin-svelte](https://github.com/DeMoorJasper/parcel-plugin-svelte) - Parcel build plugin -* [sveltify](https://github.com/tehshrike/sveltify) - Browserify transform -* [rules_svelte](https://github.com/thelgevold/rules_svelte) - Bazel Rules - -### CSS Preprocessors - -* [Less](https://github.com/ls-age/svelte-preprocess-less) -* [modular-css](https://github.com/tivac/modular-css/tree/master/packages/svelte) -* [PostCSS](https://github.com/TehShrike/svelte-preprocess-postcss) -* [Sass](https://github.com/ls-age/svelte-preprocess-sass) - -### Additional tools - -* [svelte-dev-store](https://github.com/GarethOates/svelte-dev-store) - Use Redux tools to visualise Svelte store -* More to come! - -## Example usage - -```js -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: - -| | **Values** | **Description** | **Default** | -|---|---|---|---| -| `generate` | `'dom'`, `'ssr'`, `false` | Whether to generate JavaScript code intended for use on the client (`'dom'`), or for use in server-side rendering (`'ssr'`). If `false`, component will be parsed and validated but no code will be emitted | `'dom'` | -| `dev` | `true`, `false` | Whether to enable run-time checks in the compiled component. These are helpful during development, but slow your component down. | `false` | -| `css` | `true`, `false` | Whether to include code to inject your component's styles into the DOM. | `true` | -| `hydratable` | `true`, `false` | Whether to support hydration on the compiled component. | `false` | -| `customElement` | `true`, `false`, `{ tag, props }` | Whether to compile this component to a custom element. If `tag`/`props` are passed, compiles to a custom element and overrides the values exported by the component. | `false` | -| `bind` | `boolean` | If `false`, disallows `bind:` directives | `true` | -| | | | -| `shared` | `true`, `false`, `string` | Whether to import various helpers from a shared external library. When you have a project with multiple components, this reduces the overall size of your JavaScript bundle, at the expense of having immediately-usable component. You can pass a string of the module path to use, or `true` will import from `'svelte/shared.js'`. | `false` | -| `legacy` | `true`, `false` | Ensures compatibility with very old browsers, at the cost of some extra code. | `false` | -| | | | -| `format` | `'es'`, `'amd'`, `'cjs'`, `'umd'`, `'iife'`, `'eval'` | The format to output in the compiled component.