Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] numerous FAQ updates #2112

Merged
merged 5 commits into from
Aug 7, 2021
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions documentation/faq/45-assets.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,3 +11,5 @@ You can have Vite process your assets by importing them as shown below:

<img src="{imageSrc}" />
```

There is an [open request in `vite-plugin-svelte` to help do this automatically](https://github.com/sveltejs/vite-plugin-svelte/issues/114).
12 changes: 2 additions & 10 deletions documentation/faq/70-packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,8 @@
question: How do I fix the error I'm getting trying to include a package?
---

Old beta versions of the SvelteKit template included the configuration value `noExternal: Object.keys(pkg.dependencies || {})` in `svelte.config.js`. First, please check if this line is present in your project and remove it if so. Removing this line fixes most issues and has since been removed from the template.

> Note that you can no longer directly require JSON files, since SvelteKit expects [`svelte.config.js`](/docs#configuration) to be an ES module. You can load JSON like so:
>
> ```js
> const pkg = JSON.parse(fs.readFileSync(new URL('package.json', import.meta.url), 'utf8'));
> ```

The second most commonly-encountered issue is having a Svelte component that imports a CommonJS library. In this case, you should try to work with the library authors to distribute an ESM version of the dependency. However, in the meantime, you can workaround this issue by adding the dependency to `vite.optimizeDeps.include` in `svelte.config.js`.
The most commonly-encountered issue is having a Svelte component that imports a CommonJS library. In this case, you should try to work with the library authors to distribute an ESM version of the dependency. However, in the meantime, you can workaround this issue by adding the dependency to `vite.optimizeDeps.include` in `svelte.config.js`.

Also, some older Svelte libraries don't work nicely with Vite's pre-bundling process, check out `@sveltejs/vite-plugin-svelte`'s docs for current [limitations and workarounds](https://github.com/sveltejs/vite-plugin-svelte/tree/main/packages/vite-plugin-svelte#importing-third-party-svelte-libraries).

If you are still encountering issues we recommend searching both [the Vite issue tracker](https://github.com/vitejs/vite/issues) and the issue tracker of the library in question. Sometimes issues can be worked around by fiddling with the [`optimizeDeps`](https://vitejs.dev/config/#dep-optimization-options) or [`ssr`](https://vitejs.dev/config/#ssr-options) config values.
If you are still encountering issues we recommend checking [the list of known Vite issues most commonly affecting SvelteKit users](https://github.com/sveltejs/kit/issues/2086) and searching both [the Vite issue tracker](https://github.com/vitejs/vite/issues) and the issue tracker of the library in question. Sometimes issues can be worked around by fiddling with the [`optimizeDeps`](https://vitejs.dev/config/#dep-optimization-options) or [`ssr`](https://vitejs.dev/config/#ssr-options) config values.
39 changes: 23 additions & 16 deletions documentation/faq/80-integrations.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Also see [sveltejs/integrations](https://github.com/sveltejs/integrations#svelte

### How do I use Firebase?

Please use SDK v9 which provides a modular SDK approach that's currently in beta. The old versions are very difficult to get working especially with SSR and also resulted in a much larger client download size.
Please use SDK v9 which provides a modular SDK approach that's currently in beta. The old versions are very difficult to get working especially with SSR and also resulted in a much larger client download size. Even with v9, most users need to set `kit.ssr: false` until [vite#4425](https://github.com/vitejs/vite/issues/4425) and [firebase-js-sdk#4846](https://github.com/firebase/firebase-js-sdk/issues/4846) are solved.

### How do I use a client-side only library that depends on `document` or `window`?

Expand All @@ -23,28 +23,35 @@ Vite will attempt to process all imported libraries and may fail when encounteri
If you need access to the `document` or `window` variables or otherwise need it to run only on the client-side you can wrap it in a `browser` check:

```js
benmccann marked this conversation as resolved.
Show resolved Hide resolved
import { browser } from '$app/env';
<script>
import { browser } from '$app/env';

if (browser) {
// client-only code here
}
if (browser) {
// client-only code here
}
</script>
```

You can also run code in `onMount` if you'd like to run it after the component has been first rendered to the DOM. In this case, you may still find a benefit of including a `browser` check as shown below because Vite may otherwise attempt to optimize the dependency and fail on it. [We hope to make this unnecessary in the future](https://github.com/sveltejs/svelte/issues/6372).
You can also run code in `onMount` if you'd like to run it after the component has been first rendered to the DOM:

```html
benmccann marked this conversation as resolved.
Show resolved Hide resolved
<script>
import { onMount } from 'svelte';
import { browser } from '$app/env';
import { onMount } from 'svelte';

let lib;
onMount(async () => {
const { method } = await import('some-browser-only-library');
method('hello world');
});
```

if (browser) {
onMount(async () => {
lib = (await import('some-browser-only-library')).default;
});
}
</script>
If the library you'd like to use is side-effect free you can also statically import it and it will be tree-shaken out in the server-side build where `onMount` will be automatically replaced with a no-op:

```html
benmccann marked this conversation as resolved.
Show resolved Hide resolved
import { onMount } from 'svelte';
import { method } from 'some-browser-only-library');
benmccann marked this conversation as resolved.
Show resolved Hide resolved

onMount(async () => {
benmccann marked this conversation as resolved.
Show resolved Hide resolved
method('hello world');
});
```

### How do I setup a database?
Expand Down
10 changes: 0 additions & 10 deletions documentation/faq/90-fs-strict.md

This file was deleted.