diff --git a/site/content/docs/03-compile-time.md b/site/content/docs/03-compile-time.md index 812721b7c3..307d4fe6a5 100644 --- a/site/content/docs/03-compile-time.md +++ b/site/content/docs/03-compile-time.md @@ -69,6 +69,7 @@ The following options can be passed to the compiler. None are required: | `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`, enables the `hydrate: true` runtime option, which allows a component to upgrade existing DOM rather than creating new DOM from scratch. | `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` | `true` | If `true`, styles will be included in the JavaScript class and injected at runtime. It's recommended that you set this to `false` and use the CSS that is statically generated, as it will result in smaller JavaScript bundles and better performance. diff --git a/site/content/docs/04-run-time.md b/site/content/docs/04-run-time.md index 809e34d41f..2bc55d406b 100644 --- a/site/content/docs/04-run-time.md +++ b/site/content/docs/04-run-time.md @@ -11,17 +11,6 @@ title: Run time A client-side component — that is, a component compiled with `generate: 'dom'` (or the `generate` option left unspecified) is a JavaScript class. -The following initialisation options can be provided: - -* `target` (`HTMLElement`, **required**) — the parent DOM node -* `anchor` (`HTMLElement`, default `null`) — the next sibling DOM node. Must be a child of `target` -* `props` (`Object`, default `{}`) — an object of properties to supply to the component -* `hydrate` (`boolean`, default `false`) — see below -* `intro` (`boolean`, default `false`) — whether to play in transitions on initial render - -Existing children of `target` are left where they are. - - ```js import App from './App.svelte'; @@ -35,6 +24,19 @@ const app = new App({ }); ``` +The following initialisation options can be provided: + +| option | default | description | +| --- | --- | --- | +| `target` | **none** | An `HTMLElement` to render to. This option is required +| `anchor` | `null` | A child of `target` to render the component immediately before +| `props` | `{}` | An object of proeprties to supply to the component +| `hydrate` | `false` | See below +| `intro` | `false` | If `true`, will play transitions on initial render, rather than waiting for subsequent state changes + +Existing children of `target` are left where they are. + + --- The `hydrate` option instructs Svelte to upgrade existing DOM (usually from server-side rendering) rather than creating new elements. It will only work if the component was compiled with the `hydratable: true` option. @@ -104,17 +106,164 @@ app.count += 1; ### Server-side component API -TODO - * `const result = Component.render(...)` +--- + +Unlike client-side components, server-side components don't have a lifespan after you render them — their whole job is to create some HTML and CSS. For that reason, the API is somewhat different. + +A server-side component exposes a `render` method that can be called with optional props. It returns an object with `head`, `html`, and `css` properties, where `head` contains the contents of any `` elements encountered. + +```js +const App = require('./App.svelte'); + +const { head, html, css } = App.render({ + answer: 42 +}); +``` + ### svelte -TODO +The `svelte` package exposes [lifecycle functions](tutorial/onmount) and the [context API](tutorial/context-api). + +* `onMount(() => void)` +* `onMount(() => () => void)` + +--- + +The `onMount` function schedules a callback to run as soon as the component has been mounted to the DOM. It must be called during the component's initialisation (but doesn't need to live *inside* the component; it can be called from an external module). + +`onMount` does not run inside a server-side component. + +```html + +``` + +--- + +If a function is returned from `onMount`, it will be called when the component is unmounted. + +```html + +``` + +* `beforeUpdate(() => void)` + +--- + +Schedules a callback to run immediately before the component is updated after any state change. + +> The first time the callback runs will be before the initial `onMount` + +```html + +``` + +* `afterUpdate(() => void)` + +--- + +Schedules a callback to run immediately after the component has been updated. + +```html + +``` + +* `onDestroy(() => void)` + +--- + +Schedules a callback to run once the component is unmounted. + +Out of `onMount`, `beforeUpdate`, `afterUpdate` and `onDestroy`, this is the only one that runs inside a server-side component. + +```html + +``` + +* `promise: Promise = tick()` + +--- + +Returns a promise that resolves once any pending state changes have been applied, or in the next microtask if there are none. + +```html + +``` + +* `setContext(key: any, context: any)` + +--- + +Associates an arbitrary `context` object with the current component and the specified `key`. The context is then available to children of the component (including slotted content) with `getContext`. + +Like lifecycle functions, this must be called during component initialisation. + +```html + +``` + +* `context: any = getContext(key: any)` + +--- + +Retrieves the context that belongs to the closest parent component with the specified `key`. Must be called during component initialisation. + +```html + +``` -* lifecycle methods, tick, context -* SSR behaviour ### svelte/store