diff --git a/README.md b/README.md
index bc0e396d..755d3fbd 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,7 @@
 - [What is it?](#what-is-it)
 - [Getting Started](docs/getting-started.md)
 - [Usage](docs/usage.md)
+- [Migration Guide](docs/migration-guide.md)
 - [Preprocessing](docs/preprocessing.md)
   - [Preprocessors](docs/preprocessing.md#preprocessors)
 - [Features](#features)
@@ -200,6 +201,8 @@ The current supported languages out-of-the-box are Sass, Stylus, Less, CoffeeScr
 
 ### [Usage documentation](/docs/usage.md)
 
+### [Migration Guide](/docs/migration-guide.md)
+
 ---
 
 ## License
diff --git a/docs/migration-guide.md b/docs/migration-guide.md
new file mode 100644
index 00000000..f16693a7
--- /dev/null
+++ b/docs/migration-guide.md
@@ -0,0 +1,88 @@
+<!-- @import "[TOC]" {cmd="toc" depthFrom=1 depthTo=6 orderedList=false} -->
+
+<!-- code_chunk_output -->
+
+- [From `v3` to `v4`](#from-v3-to-v4)
+  - [Prepending content to `scss`](#prepending-content-to-scss)
+  - [Executing some function before preprocessing](#executing-some-function-before-preprocessing)
+  - [Defining preprocessor properties](#defining-preprocessor-properties)
+
+<!-- /code_chunk_output -->
+
+## From `v3` to `v4`
+
+### Prepending content to `scss`
+
+In `v3`, it was possible to prepend some content for the `scss` language through the `data` property.
+
+```js
+import sveltePreprocess from 'svelte-preprocess';
+
+sveltePreprocess({
+  scss: {
+    data: '// prepended content',
+  },
+});
+```
+
+In `v4`, not only `scss`, but every language preprocessor accepts the new `prependData` property. The `data` property is no longer supported.
+
+```js
+import sveltePreprocess from 'svelte-preprocess';
+
+sveltePreprocess({
+  scss: {
+    prependData: '// prepended content for scss',
+  },
+  typescript: {
+    prependData: '// prepended content for ts',
+  },
+});
+```
+
+### Executing some function before preprocessing
+
+The previously `onBefore` property was removed. Instead, enqueue a custom preprocessor before `svelte-preprocess`.
+
+```js
+// v3
+
+{
+  preprocess: sveltePreprocess({
+    onBefore({ content, filename }) {
+      return content.replace('foo', 'bar');
+    },
+  });
+}
+
+// v4
+const myPreprocessor = {
+  markup({ content }) {
+    return { code: content.replace('foo', 'bar') };
+  },
+};
+
+// later in your config
+{
+  preprocess: [myPreprocessor, sveltePreprocess()];
+}
+```
+
+### Defining preprocessor properties
+
+The previously `transformers` property was removed. Instead, define your preprocessor options in the root object of `svelte-preprocess` auto-preprocessor.
+
+```diff
+import sveltePreprocess from 'svelte-preprocess';
+
+sveltePreprocess({
+-  transformers: {
+     scss: { ... }
+-  }
+});
+```
+
+
+### Type-checking components
+
+> TODO
\ No newline at end of file