msb-public
/
svelte
mirror of https://github.com/sveltejs/svelte
1
0
Code Issues Projects Releases Wiki Activity

docs(sites): Auto-generated CompileOptions (#8756)

Browse Source 
---------

Co-authored-by: Simon H <5968653+dummdidumm@users.noreply.github.com>
Co-authored-by: Simon Holthausen <simon.holthausen@vercel.com>
pull/8480/head
Puru Vijay 1 year ago committed by GitHub
parent f8139e5a6e
commit 88504ee90a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 192 additions and 317 deletions
Show Stats Download Patch File Download Diff File

109
documentation/docs/04-compiler-and-api/01-svelte-compiler.md
Unescape View File

@ -29,56 +29,7 @@ const result = compile(source, {
}); });
``` ```
The following options can be passed to the compiler. None are required: Refer to [CompileOptions](#type-compileoptions) for all the available options.
<!-- | option | type | default
| --- | --- | --- |
| `filename` | string | `null`
| `name` | string | `"Component"`
| `generate` | `"dom"` or `"ssr"` or `false` | `"dom"`
| `errorMode` | `"throw"` or `"warn"` | `"throw"`
| `varsReport` | `"strict"` or `"full"` or `false` | `"strict"`
| `dev` | boolean | `false`
| `immutable` | boolean | `false`
| `hydratable` | boolean | `false`
| `legacy` | boolean | `false`
| `customElement` | boolean | `false`
| `tag` | string | null
| `accessors` | boolean | `false`
| `css` | boolean | `true`
| `loopGuardTimeout` | number | 0
| `preserveComments` | boolean | `false`
| `preserveWhitespace` | boolean | `false`
| `outputFilename` | string | `null`
| `cssOutputFilename` | string | `null`
| `sveltePath` | string | `"svelte"` -->
| option | default | description |
| -------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filename` | `null` | `string` used for debugging hints and sourcemaps. Your bundler plugin will set it automatically. |
| `name` | `"Component"` | `string` that sets the name of the resulting JavaScript class (though the compiler will rename it if it would otherwise conflict with other variables in scope). It will normally be inferred from `filename`. |
| `generate` | `"dom"` | If `"dom"`, Svelte emits a JavaScript class for mounting to the DOM. If `"ssr"`, Svelte emits an object with a `render` method suitable for server-side rendering. If `false`, no JavaScript or CSS is returned; just metadata. |
| `errorMode` | `"throw"` | If `"throw"`, Svelte throws when a compilation error occurred. If `"warn"`, Svelte will treat errors as warnings and add them to the warning report. |
| `varsReport` | `"strict"` | If `"strict"`, Svelte returns a variables report with only variables that are not globals nor internals. If `"full"`, Svelte returns a variables report with all detected variables. If `false`, no variables report is returned. |
| `dev` | `false` | If `true`, causes extra code to be added to components that will perform runtime checks and provide debugging information during development. |
| `immutable` | `false` | If `true`, tells the compiler that you promise not to mutate any objects. This allows it to be less conservative about checking whether values have changed. |
| `hydratable` | `false` | If `true` when generating DOM code, enables the `hydrate: true` runtime option, which allows a component to upgrade existing DOM rather than creating new DOM from scratch. When generating SSR code, this adds markers to `<head>` elements so that hydration knows which to replace. |
| `legacy` | `false` | If `true`, generates code that will work in IE9 and IE10, which don't support things like `element.dataset`. |
| `accessors` | `false` | If `true`, getters and setters will be created for the component's props. If `false`, they will only be created for readonly exported values (i.e. those declared with `const`, `class` and `function`). If compiling with `customElement: true` this option defaults to `true`. |
| `customElement` | `false` | If `true`, tells the compiler to generate a custom element constructor instead of a regular Svelte component. |
| `tag` | `null` | A `string` that tells Svelte what tag name to register the custom element with. It must be a lowercase alphanumeric string with at least one hyphen, e.g. `"my-element"`. |
| `css` | `'injected'` | If `'injected'` (formerly `true`), styles will be included in the JavaScript class and injected at runtime for the components actually rendered. If `'external'` (formerly `false`), the CSS will be returned in the `css` field of the compilation result. Most Svelte bundler plugins will set this to `'external'` and use the CSS that is statically generated for better performance, as it will result in smaller JavaScript bundles and the output can be served as cacheable `.css` files. If `'none'`, styles are completely avoided and no CSS output is generated. |
| `cssHash` | See right | A function that takes a `{ hash, css, name, filename }` argument and returns the string that is used as a classname for scoped CSS. It defaults to returning `svelte-${hash(css)}` |
| `loopGuardTimeout` | 0 | A `number` that tells Svelte to break the loop if it blocks the thread for more than `loopGuardTimeout` ms. This is useful to prevent infinite loops. **Only available when `dev: true`** |
| `preserveComments` | `false` | If `true`, your HTML comments will be preserved during server-side rendering. By default, they are stripped out. |
| `preserveWhitespace` | `false` | If `true`, whitespace inside and between elements is kept as you typed it, rather than removed or collapsed to a single space where possible. |
| `sourcemap` | `object \| string` | An initial sourcemap that will be merged into the final output sourcemap. This is usually the preprocessor sourcemap. |
| `enableSourcemap` | `boolean \| { js: boolean; css: boolean; }` | If `true`, Svelte generate sourcemaps for components. Use an object with `js` or `css` for more granular control of sourcemap generation. By default, this is `true`. |
| `outputFilename` | `null` | A `string` used for your JavaScript sourcemap. |
| `cssOutputFilename` | `null` | A `string` used for your CSS sourcemap. |
| `sveltePath` | `"svelte"` | The location of the `svelte` package. Any imports from `svelte` or `svelte/[module]` will be modified accordingly. |
| `namespace` | `"html"` | The namespace of the element; e.g., `"mathml"`, `"svg"`, `"foreign"`. |
| `format` | `"esm"` | This option only exists in Svelte 3. In Svelte 4 only ESM can be output. `"esm"` creates a JavaScript module (with `import` and `export`). `"cjs"` creates a CommonJS module (with `require` and `module.exports`). |
The returned `result` object contains the code for your component, along with useful bits of metadata. The returned `result` object contains the code for your component, along with useful bits of metadata.
@ -96,63 +47,7 @@ import { compile } from 'svelte/compiler';
const { js, css, ast, warnings, vars, stats } = compile(source); const { js, css, ast, warnings, vars, stats } = compile(source);
``` ```
- `js` and `css` are objects with the following properties: Refer to [CompileResult](#type-compileresult) for a full description of the compile result.
- `code` is a JavaScript string
- `map` is a sourcemap with additional `toString()` and `toUrl()` convenience methods
- `ast` is an abstract syntax tree representing the structure of your component.
- `warnings` is an array of warning objects that were generated during compilation. Each warning has several properties:
- `code` is a string identifying the category of warning
- `message` describes the issue in human-readable terms
- `start` and `end`, if the warning relates to a specific location, are objects with `line`, `column` and `character` properties
- `frame`, if applicable, is a string highlighting the offending code with line numbers
- `vars` is an array of the component's declarations, used by [eslint-plugin-svelte3](https://github.com/sveltejs/eslint-plugin-svelte3) for example. Each variable has several properties:
- `name` is self-explanatory
- `export_name` is the name the value is exported as, if it is exported (will match `name` unless you do `export...as`)
- `injected` is `true` if the declaration is injected by Svelte, rather than in the code you wrote
- `module` is `true` if the value is declared in a `context="module"` script
- `mutated` is `true` if the value's properties are assigned to inside the component
- `reassigned` is `true` if the value is reassigned inside the component
- `referenced` is `true` if the value is used in the template
- `referenced_from_script` is `true` if the value is used in the `<script>` outside the declaration
- `writable` is `true` if the value was declared with `let` or `var` (but not `const`, `class` or `function`)
- `stats` is an object used by the Svelte developer team for diagnosing the compiler. Avoid relying on it to stay the same!
<!--
```js
compiled: {
// `map` is a v3 sourcemap with toString()/toUrl() methods
js: { code: string, map: {...} },
css: { code: string, map: {...} },
ast: {...}, // ESTree-like syntax tree for the component, including HTML, CSS and JS
warnings: Array<{
code: string,
message: string,
filename: string,
pos: number,
start: { line: number, column: number },
end: { line: number, column: number },
frame: string,
toString: () => string
}>,
vars: Array<{
name: string,
export_name: string,
injected: boolean,
module: boolean,
mutated: boolean,
reassigned: boolean,
referenced: boolean,
referenced_from_script: boolean,
writable: boolean
}>,
stats: {
timings: { [label]: number }
}
} = svelte.compile(source: string, options?: {...})
```
-->
## parse ## parse

5
packages/svelte/src/compiler/compile/Component.js
Unescape View File

@ -314,7 +314,10 @@ export default class Component {
return alias; return alias;
} }
/** @param {{ js: import('estree').Node[]; css: import('../interfaces.js').CssResult }} [result] */ /**
* @param {{ js: import('estree').Node[]; css: import('../interfaces.js').CssResult }} [result]
* @returns {import('../interfaces.js').CompileResult}
*/
generate(result) { generate(result) {
let js = null; let js = null;
let css = null; let css = null;

203
packages/svelte/src/compiler/compile/internal_exports.ts
Unescape View File

@ -1,203 +0,0 @@
// This file is automatically generated
export default new Set([
'HtmlTag',
'HtmlTagHydration',
'ResizeObserverSingleton',
'SvelteComponent',
'SvelteComponentDev',
'SvelteComponentTyped',
'SvelteElement',
'action_destroyer',
'add_attribute',
'add_classes',
'add_flush_callback',
'add_iframe_resize_listener',
'add_location',
'add_render_callback',
'add_styles',
'add_transform',
'afterUpdate',
'append',
'append_dev',
'append_empty_stylesheet',
'append_hydration',
'append_hydration_dev',
'append_styles',
'assign',
'attr',
'attr_dev',
'attribute_to_object',
'beforeUpdate',
'bind',
'binding_callbacks',
'blank_object',
'bubble',
'check_outros',
'children',
'claim_comment',
'claim_component',
'claim_element',
'claim_html_tag',
'claim_space',
'claim_svg_element',
'claim_text',
'clear_loops',
'comment',
'component_subscribe',
'compute_rest_props',
'compute_slots',
'construct_svelte_component',
'construct_svelte_component_dev',
'contenteditable_truthy_values',
'createEventDispatcher',
'create_animation',
'create_bidirectional_transition',
'create_component',
'create_custom_element',
'create_in_transition',
'create_out_transition',
'create_slot',
'create_ssr_component',
'current_component',
'custom_event',
'dataset_dev',
'debug',
'destroy_block',
'destroy_component',
'destroy_each',
'detach',
'detach_after_dev',
'detach_before_dev',
'detach_between_dev',
'detach_dev',
'dirty_components',
'dispatch_dev',
'each',
'element',
'element_is',
'empty',
'end_hydrating',
'escape',
'escape_attribute_value',
'escape_object',
'exclude_internal_props',
'fix_and_destroy_block',
'fix_and_outro_and_destroy_block',
'fix_position',
'flush',
'flush_render_callbacks',
'getAllContexts',
'getContext',
'get_all_dirty_from_scope',
'get_binding_group_value',
'get_current_component',
'get_custom_elements_slots',
'get_root_for_style',
'get_slot_changes',
'get_spread_object',
'get_spread_update',
'get_store_value',
'get_svelte_dataset',
'globals',
'group_outros',
'handle_promise',
'hasContext',
'has_prop',
'head_selector',
'identity',
'init',
'init_binding_group',
'init_binding_group_dynamic',
'insert',
'insert_dev',
'insert_hydration',
'insert_hydration_dev',
'intros',
'invalid_attribute_name_character',
'is_client',
'is_crossorigin',
'is_empty',
'is_function',
'is_promise',
'is_void',
'listen',
'listen_dev',
'loop',
'loop_guard',
'merge_ssr_styles',
'missing_component',
'mount_component',
'noop',
'not_equal',
'now',
'null_to_empty',
'object_without_properties',
'onDestroy',
'onMount',
'once',
'outro_and_destroy_block',
'prevent_default',
'prop_dev',
'query_selector_all',
'raf',
'resize_observer_border_box',
'resize_observer_content_box',
'resize_observer_device_pixel_content_box',
'run',
'run_all',
'safe_not_equal',
'schedule_update',
'select_multiple_value',
'select_option',
'select_options',
'select_value',
'self',
'setContext',
'set_attributes',
'set_current_component',
'set_custom_element_data',
'set_custom_element_data_map',
'set_data',
'set_data_contenteditable',
'set_data_contenteditable_dev',
'set_data_dev',
'set_data_maybe_contenteditable',
'set_data_maybe_contenteditable_dev',
'set_dynamic_element_data',
'set_input_type',
'set_input_value',
'set_now',
'set_raf',
'set_store_value',
'set_style',
'set_svg_attributes',
'space',
'split_css_unit',
'spread',
'src_url_equal',
'start_hydrating',
'stop_immediate_propagation',
'stop_propagation',
'subscribe',
'svg_element',
'text',
'tick',
'time_ranges_to_array',
'to_number',
'toggle_class',
'transition_in',
'transition_out',
'trusted',
'update_await_block_branch',
'update_keyed_each',
'update_slot',
'update_slot_base',
'validate_component',
'validate_dynamic_element',
'validate_each_argument',
'validate_each_keys',
'validate_slots',
'validate_store',
'validate_void_dynamic_element',
'xlink_attr'
]);

180
packages/svelte/src/compiler/interfaces.d.ts vendored
Unescape View File

@ -169,31 +169,180 @@ export type CssHashGetter = (args: {
}) => string; }) => string;
export interface CompileOptions { export interface CompileOptions {
/**
* Sets the name of the resulting JavaScript class (though the compiler will rename it if it would otherwise conflict with other variables in scope).
* It will normally be inferred from `filename`
*
* @default 'Component'
*/
name?: string; name?: string;
/**
* Used for debugging hints and sourcemaps. Your bundler plugin will set it automatically.
*
* @default null
*/
filename?: string; filename?: string;
/**
* If `"dom"`, Svelte emits a JavaScript class for mounting to the DOM.
* If `"ssr"`, Svelte emits an object with a `render` method suitable for server-side rendering.
* If `false`, no JavaScript or CSS is returned; just metadata.
*
* @default 'dom'
*/
generate?: 'dom' | 'ssr' | false; generate?: 'dom' | 'ssr' | false;
/**
* If `"throw"`, Svelte throws when a compilation error occurred.
* If `"warn"`, Svelte will treat errors as warnings and add them to the warning report.
*
* @default 'throw'
*/
errorMode?: 'throw' | 'warn'; errorMode?: 'throw' | 'warn';
/**
* If `"strict"`, Svelte returns a variables report with only variables that are not globals nor internals.
* If `"full"`, Svelte returns a variables report with all detected variables.
* If `false`, no variables report is returned.
*
* @default 'strict'
*/
varsReport?: 'full' | 'strict' | false; varsReport?: 'full' | 'strict' | false;
/**
* An initial sourcemap that will be merged into the final output sourcemap.
* This is usually the preprocessor sourcemap.
*
* @default null
*/
sourcemap?: object | string; sourcemap?: object | string;
/**
* If `true`, Svelte generate sourcemaps for components.
* Use an object with `js` or `css` for more granular control of sourcemap generation.
*
* @default true
*/
enableSourcemap?: EnableSourcemap; enableSourcemap?: EnableSourcemap;
/**
* Used for your JavaScript sourcemap.
*
* @default null
*/
outputFilename?: string; outputFilename?: string;
/**
* Used for your CSS sourcemap.
*
* @default null
*/
cssOutputFilename?: string; cssOutputFilename?: string;
/**
* The location of the `svelte` package.
* Any imports from `svelte` or `svelte/[module]` will be modified accordingly.
*
* @default 'svelte'
*/
sveltePath?: string; sveltePath?: string;
/**
* If `true`, causes extra code to be added to components that will perform runtime checks and provide debugging information during development.
*
* @default false
*/
dev?: boolean; dev?: boolean;
/**
* If `true`, getters and setters will be created for the component's props. If `false`, they will only be created for readonly exported values (i.e. those declared with `const`, `class` and `function`). If compiling with `customElement: true` this option defaults to `true`.
*
* @default false
*/
accessors?: boolean; accessors?: boolean;
/**
* If `true`, tells the compiler that you promise not to mutate any objects.
* This allows it to be less conservative about checking whether values have changed.
*
* @default false
*/
immutable?: boolean; immutable?: boolean;
/**
* If `true` when generating DOM code, enables the `hydrate: true` runtime option, which allows a component to upgrade existing DOM rather than creating new DOM from scratch.
* When generating SSR code, this adds markers to `<head>` elements so that hydration knows which to replace.
*
* @default false
*/
hydratable?: boolean; hydratable?: boolean;
/**
* If `true`, generates code that will work in IE9 and IE10, which don't support things like `element.dataset`.
*
* @default false
*/
legacy?: boolean; legacy?: boolean;
/**
* If `true`, tells the compiler to generate a custom element constructor instead of a regular Svelte component.
*
* @default false
*/
customElement?: boolean; customElement?: boolean;
/**
* A `string` that tells Svelte what tag name to register the custom element with.
* It must be a lowercase alphanumeric string with at least one hyphen, e.g. `"my-element"`.
*
* @default null
*/
tag?: string; tag?: string;
/**
* - `'injected'` (formerly `true`), styles will be included in the JavaScript class and injected at runtime for the components actually rendered.
* - `'external'` (formerly `false`), the CSS will be returned in the `css` field of the compilation result. Most Svelte bundler plugins will set this to `'external'` and use the CSS that is statically generated for better performance, as it will result in smaller JavaScript bundles and the output can be served as cacheable `.css` files.
* - `'none'`, styles are completely avoided and no CSS output is generated.
*/
css?: 'injected' | 'external' | 'none' | boolean; css?: 'injected' | 'external' | 'none' | boolean;
/**
* A `number` that tells Svelte to break the loop if it blocks the thread for more than `loopGuardTimeout` ms.
* This is useful to prevent infinite loops.
* **Only available when `dev: true`**.
*
* @default 0
*/
loopGuardTimeout?: number; loopGuardTimeout?: number;
/**
* The namespace of the element; e.g., `"mathml"`, `"svg"`, `"foreign"`.
*
* @default 'html'
*/
namespace?: string; namespace?: string;
/**
* A function that takes a `{ hash, css, name, filename }` argument and returns the string that is used as a classname for scoped CSS.
* It defaults to returning `svelte-${hash(css)}`.
*
* @default undefined
*/
cssHash?: CssHashGetter; cssHash?: CssHashGetter;
/**
* If `true`, your HTML comments will be preserved during server-side rendering. By default, they are stripped out.
*
* @default false
*/
preserveComments?: boolean; preserveComments?: boolean;
/**
* If `true`, whitespace inside and between elements is kept as you typed it, rather than removed or collapsed to a single space where possible.
*
* @default false
*/
preserveWhitespace?: boolean; preserveWhitespace?: boolean;
} }
@ -241,3 +390,34 @@ export interface CssResult {
code: string; code: string;
map: SourceMap; map: SourceMap;
} }
/** The returned shape of `compile` from `svelte/compiler` */
export interface CompileResult {
/** The resulting JavaScript code from compling the component */
js: {
/** Code as a string */
code: string;
/** A source map */
map: any;
};
/** The resulting CSS code from compling the component */
css: CssResult;
/** The abstract syntax tree representing the structure of the component */
ast: Ast;
/**
* An array of warning objects that were generated during compilation. Each warning has several properties:
* - code is a string identifying the category of warning
* - message describes the issue in human-readable terms
* - start and end, if the warning relates to a specific location, are objects with line, column and character properties
* - frame, if applicable, is a string highlighting the offending code with line numbers
* */
warnings: Warning[];
/** An array of the component's declarations used by tooling in the ecosystem (like our ESLint plugin) to infer more information */
vars: Var[];
/** An object used by the Svelte developer team for diagnosing the compiler. Avoid relying on it to stay the same! */
stats: {
timings: {
total: number;
};
};
}

2
packages/svelte/src/compiler/public.d.ts vendored
Unescape View File

@ -1,3 +1,3 @@
export { CompileOptions, EnableSourcemap, CssHashGetter } from './interfaces'; export { CompileOptions, CompileResult, EnableSourcemap, CssHashGetter } from './interfaces';
export * from './preprocess/public.js'; export * from './preprocess/public.js';
export * from './index.js'; export * from './index.js';

8
pnpm-lock.yaml
Unescape View File

@ -182,8 +182,8 @@ importers:
specifier: ^1.20.4 specifier: ^1.20.4
version: 1.20.4(svelte@packages+svelte)(vite@4.3.9) version: 1.20.4(svelte@packages+svelte)(vite@4.3.9)
'@sveltejs/site-kit': '@sveltejs/site-kit':
specifier: 6.0.0-next.5 specifier: 6.0.0-next.6
version: 6.0.0-next.5(@sveltejs/kit@1.20.4)(svelte@packages+svelte) version: 6.0.0-next.6(@sveltejs/kit@1.20.4)(svelte@packages+svelte)
'@sveltejs/vite-plugin-svelte': '@sveltejs/vite-plugin-svelte':
specifier: ^2.4.1 specifier: ^2.4.1
version: 2.4.1(svelte@packages+svelte)(vite@4.3.9) version: 2.4.1(svelte@packages+svelte)(vite@4.3.9)
@ -1822,8 +1822,8 @@ packages:
svelte-local-storage-store: 0.4.0(svelte@packages+svelte) svelte-local-storage-store: 0.4.0(svelte@packages+svelte)
dev: false dev: false
/@sveltejs/site-kit@6.0.0-next.5(@sveltejs/kit@1.20.4)(svelte@packages+svelte): /@sveltejs/site-kit@6.0.0-next.6(@sveltejs/kit@1.20.4)(svelte@packages+svelte):
resolution: {integrity: sha512-3CoOvWEWIuf/LQdpMpb9Tp8rcGeZ5Lyc142xiRLcdrXboIb5tkLX9gDCqITFy/kxQppsrIPMNuognAXsgDVKOg==} resolution: {integrity: sha512-5+NjcAzksiCkQrgKe9Kj3L8yMqGSF73QJnV949gFOzxY2VjTNeCJCQ4fl7Ek64/j5YrLEdFaz0DbYNqZzes8qg==}
peerDependencies: peerDependencies:
'@sveltejs/kit': ^1.0.0 '@sveltejs/kit': ^1.0.0
svelte: ^3.54.0 || ^4.0.0-next.0 || ^4.0.0 svelte: ^3.54.0 || ^4.0.0-next.0 || ^4.0.0

2
sites/svelte.dev/package.json
Unescape View File

@ -30,7 +30,7 @@
"@resvg/resvg-js": "^2.4.1", "@resvg/resvg-js": "^2.4.1",
"@sveltejs/adapter-vercel": "^3.0.1", "@sveltejs/adapter-vercel": "^3.0.1",
"@sveltejs/kit": "^1.20.4", "@sveltejs/kit": "^1.20.4",
"@sveltejs/site-kit": "6.0.0-next.5", "@sveltejs/site-kit": "6.0.0-next.6",
"@sveltejs/vite-plugin-svelte": "^2.4.1", "@sveltejs/vite-plugin-svelte": "^2.4.1",
"@types/marked": "^5.0.0", "@types/marked": "^5.0.0",
"@types/node": "^20.3.1", "@types/node": "^20.3.1",

Write Preview
Loading…
Cancel
Save