From bca88831dab9f8a3ff38c56e68229e7b3d63d3f1 Mon Sep 17 00:00:00 2001
From: Richard Harris <richard.a.harris@gmail.com>
Date: Tue, 30 Apr 2019 09:25:40 -0400
Subject: [PATCH] add 0.26 migration guide

---
 site/content/migrating/01-migrating.md | 106 ++++++++++++++++++++++++-
 1 file changed, 105 insertions(+), 1 deletion(-)

diff --git a/site/content/migrating/01-migrating.md b/site/content/migrating/01-migrating.md
index 883624d..409812f 100644
--- a/site/content/migrating/01-migrating.md
+++ b/site/content/migrating/01-migrating.md
@@ -2,7 +2,111 @@
 title: Migrating
 ---
 
-Until we reach version 1.0, there may be occasional changes to the project structure Sapper expects. If you upgrade and Sapper sends you here, it's because it was unable to fix your project automatically.
+
+Until we reach version 1.0, there may be occasional changes to the project structure Sapper expects.
+
+
+### 0.25 to 0.26
+
+The most significant change yet: Sapper is now built on Svelte 3.
+
+#### Importing Sapper
+
+Your app is now built to `src/node_modules/@sapper` — this allows you to easily import it from anywhere in your source code. Update your `server.js`...
+
+```diff
+// src/server.js
+-import * as sapper from '../__sapper__/server.js';
++import * as sapper from '@sapper/server';
+```
+
+...and client.js:
+
+```diff
+-import * as sapper from '../__sapper__/client.js';
++import * as sapper from '@sapper/app';
+
+sapper.start({
+	target: document.querySelector('#sapper')
+});
+```
+
+The same applies to imports like `goto` and `prefetchRoutes`.
+
+
+#### Webpack config
+
+If you're using webpack, you must update your configuration to recognise `.mjs` and `.svelte` files:
+
+```js
+resolve: {
+	extensions: ['.mjs', '.js', '.json', '.svelte', '.html']
+}
+```
+
+If you're using .svelte files (recommended), you'll also need to tell `svelte-loader` to expect them:
+
+```diff
+-test: /\.html$/
++test: /\.(svelte|html)$/
+```
+
+
+#### Session data
+
+Passing data from server to client is now accomplished with a `session` function passed to the middleware:
+
+```js
+// src/server.js
+sapper.middleware({
+	session: (req, res) => ({
+		// session data goes here
+	})
+})
+```
+
+This data is available in `preload` functions as the second argument:
+
+```html
+<!-- SomeComponent.svelte -->
+<script context="module">
+	export function preload(page, session) {
+		const { path, params, query } = page; // as before
+
+		if (!session.user) return this.redirect(302, 'login');
+		// ...
+	}
+</script>
+```
+
+
+#### Stores
+
+It is also available, along with `page` and `preloading`, as a store inside components:
+
+```html
+<script>
+	import * as sapper from '@sapper/app';
+	const { page, preloading, session } = sapper.stores();
+</script>
+```
+
+`page` and `preloading` are [readable stores](https://svelte.dev/tutorial/readable-stores), while `session` is [writable](https://svelte.dev/tutorial/writable-stores).
+
+
+#### Layouts
+
+Your layout components should now use a `<slot>` element to render nested routes, instead of `<svelte:component>`:
+
+```diff
+<main>
+-	<svelte:component this={child.component} {...child.props}/>
++	<slot></slot>
+</main>
+```
+
+The layout component itself receives a `segment` prop, which is equivalent to `child.segment` in earlier versions.
+
 
 ### 0.21 to 0.22