From f98ab575ef46a8e8bd389f5e26c4941db12286d5 Mon Sep 17 00:00:00 2001 From: Conduitry Date: Thu, 9 Mar 2017 08:02:39 -0500 Subject: [PATCH 1/2] add more formal documentation for API options (#355) --- README.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 90 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 793c37e7c4..b79e924616 100644 --- a/README.md +++ b/README.md @@ -22,14 +22,14 @@ This is the Svelte compiler, which is primarily intended for authors of tooling * More to come! -## API +## Example usage ```js import * as svelte from 'svelte'; const { code, map } = svelte.compile( source, { // the target module format – defaults to 'es' (ES2015 modules), can - // also be 'amd', 'cjs', 'umd' or 'iife' + // also be 'amd', 'cjs', 'umd', 'iife' or 'eval' format: 'umd', // the filename of the source file, used in e.g. generating sourcemaps @@ -58,6 +58,94 @@ const { code, map } = svelte.compile( source, { ``` +## API + +The Svelte compiler exposes the following API: + +* `compile( source [, options ] ) => { code, map }` - Compile the component with the given options (see below). Returns an object containing the compiled JavaScript and a sourcemap. +* `create( source [, options ] ) => function` - Compile the component and return the component itself. +* `VERSION` - The version of this copy of the Svelte compiler as a string, `'x.x.x'`. + +### Options + +The Svelte compiler optionally takes a second argument, an object of configuration options: + + + + + + + + + + + + + + + +
+ **Values** + **Description** + **Default** + +
`format` + `'es'`, `'amd'`, `'cjs'`, `'umd'`, `'iife'`, `'eval'` + The format to output in the compiled component.
`'es'` - ES6/ES2015 module, suitable for consumption by a bundler
`'amd'` - AMD module
`'cjs'` - CommonJS module
`'iife'` - IIFE-wrapped function defining a global variable, suitable for use directly in browser
`'eval'` - standalone function, suitable for passing to `eval()` + 		`'es'` + +
`generate` + `'dom'`, `'ssr'` + Whether to generate JavaScript code intended for use on the client (`'dom'`), or for use in server-side rendering (`'ssr'`). + `'dom'` + +
`name` + `string` + The name of the constructor in the compiled component. + `'SvelteComponent'` + +
`filename` + `string` + The filename to use in sourcemaps and compiler error and warning messages. + `'SvelteComponent.html'` + +
`amd`.`id` + `string` + The AMD module ID to use for the `'amd'` and `'umd'` output formats. + `undefined` + +
`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` + +
`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` + +
`globals` + `object`, `function` + When outputting to the `'umd'`, `'iife'` or `'eval'` formats, an object or function mapping the names of imported dependencies to the names of global variables. + `{}` + +
`onerror` + `function` + Specify a callback for when Svelte encounters an error while compiling the component. + (exception is thrown) + +
`onwarn` + `function` + Specify a callback for when Svelte encounters a non-fatal warning while compiling the component. + (warning is logged to console) + +
+ ## Example/starter repos * [charpeni/svelte-example](https://github.com/charpeni/svelte-example) - Some Svelte examples with configured Rollup, Babel, ESLint, directives, Two-Way binding, and nested components From b6357442a94051fdfc7ee26f05ac178d1825dbf5 Mon Sep 17 00:00:00 2001 From: Conduitry Date: Thu, 9 Mar 2017 08:15:52 -0500 Subject: [PATCH 2/2] fix options table formatting --- README.md | 88 ++++++++----------------------------------------------- 1 file changed, 13 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index b79e924616..e0d96054df 100644 --- a/README.md +++ b/README.md @@ -70,81 +70,19 @@ The Svelte compiler exposes the following API: The Svelte compiler optionally takes a second argument, an object of configuration options: - - - - - - - - - - - - - - -
- **Values** - **Description** - **Default** - -
`format` - `'es'`, `'amd'`, `'cjs'`, `'umd'`, `'iife'`, `'eval'` - The format to output in the compiled component.
`'es'` - ES6/ES2015 module, suitable for consumption by a bundler
`'amd'` - AMD module
`'cjs'` - CommonJS module
`'iife'` - IIFE-wrapped function defining a global variable, suitable for use directly in browser
`'eval'` - standalone function, suitable for passing to `eval()` - 		`'es'` - -
`generate` - `'dom'`, `'ssr'` - Whether to generate JavaScript code intended for use on the client (`'dom'`), or for use in server-side rendering (`'ssr'`). - `'dom'` - -
`name` - `string` - The name of the constructor in the compiled component. - `'SvelteComponent'` - -
`filename` - `string` - The filename to use in sourcemaps and compiler error and warning messages. - `'SvelteComponent.html'` - -
`amd`.`id` - `string` - The AMD module ID to use for the `'amd'` and `'umd'` output formats. - `undefined` - -
`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` - -
`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` - -
`globals` - `object`, `function` - When outputting to the `'umd'`, `'iife'` or `'eval'` formats, an object or function mapping the names of imported dependencies to the names of global variables. - `{}` - -
`onerror` - `function` - Specify a callback for when Svelte encounters an error while compiling the component. - (exception is thrown) - -
`onwarn` - `function` - Specify a callback for when Svelte encounters a non-fatal warning while compiling the component. - (warning is logged to console) - -
+| | **Values** | **Description** | **Defaults** | +|---|---|---|---| +| `format` | `'es'`, `'amd'`, `'cjs'`, `'umd'`, `'iife'`, `'eval'` | The format to output in the compiled component.
`'es'` - ES6/ES2015 module, suitable for consumption by a bundler
`'amd'` - AMD module
`'cjs'` - CommonJS module
`'iife'` - IIFE-wrapped function defining a global variable, suitable for use directly in browser
`'eval'` - standalone function, suitable for passing to `eval()` | `'es'` | +| `generate` | `'dom'`, `'ssr'` | Whether to generate JavaScript code intended for use on the client (`'dom'`), or for use in server-side rendering (`'ssr'`). | `'dom'` | +| `name` | `string` | The name of the constructor in the compiled component. | `'SvelteComponent'` | +| `filename` | `string` | The filename to use in sourcemaps and compiler error and warning messages. | `'SvelteComponent.html'` | +| `amd`.`id` | `string` | The AMD module ID to use for the `'amd'` and `'umd'` output formats. | `undefined` | +| `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` | +| `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` | +| `globals` | `object`, `function` | When outputting to the `'umd'`, `'iife'` or `'eval'` formats, an object or function mapping the names of imported dependencies to the names of global variables. | `{}` | +| `onerror` | `function` | Specify a callback for when Svelte encounters an error while compiling the component. | (exception is thrown) | +| `onwarn` | `function` | Specify a callback for when Svelte encounters a non-fatal warning while compiling the component. | (warning is logged to console) | ## Example/starter repos