Expo Svelte
GitHub
Module On the device
$app/navigation goto drives the app's router. preloadCode loads a screen's code. The rest throws a message that names it.
$app/state page is the screen the user sees. updated follows the over-the-air updates. navigating is never in flight.
$app/env browser is false, dev is __DEV__, version is the app's version, and mobile is true.
$app/environment The name SvelteKit 3 deprecates $app/env under: the same module.
$app/paths resolve builds the path of a route. asset and match too.
svelte/motion Svelte's own. prefersReducedMotion reads the system's setting.
svelte/reactivity MediaQuery and window.matchMedia read the window's size, the scheme and the accessibility settings. svelte/reactivity/window is the window's size (Platform APIs).

The types are SvelteKit's own, so install @sveltejs/kit in the project and nothing needs declaring. The library adds one export, mobile, and its declaration comes with the library: a program that has your vite.config.ts sees it through the plugin it imports, and one that has your native screens through the router they import.

goto(url, options?) from $app/navigation goes to a route of the app, through the root router, from any code. Routing has what it does, its options and what rejects it. Called in an $effect, it doesn't make the effect depend on the screens: $effect(() => { if (!signedIn) goto('/sign-in', { replace: true }) }) runs again when signedIn changes and not when the user opens another screen.

src/lib/session.ts
import { goto } from '$app/navigation';

export async function signedOut() {
	await goto('/sign-in', { replace: true });
}

preloadCode(routeId) loads the code of the route with that id ('/posts/[id]', with the groups of its directory: '/(app)/posts/[id]'): the page and the layouts it brings, or the layout of a tabs or stack navigator, which has an id of its own. The navigation that follows has less to import. It resolves when the code is loaded, rejects with what a failed load threw, and rejects for an id no route has. It loads code only: there is no load function to run. disableScrollHandling does nothing, since a screen has no scroll handling for it to disable.

SvelteKit declares the rest of the module, so an import of one of them type-checks, and the function throws when it is called. The router has nothing honest behind them:

Function What it says
beforeNavigate, afterNavigate, onNavigate the router has no navigation hooks. To follow the screen, read page.url in an $effect.
invalidate, invalidateAll, refreshAll, preloadData a screen has no load function to run again. refreshAll of expo-svelte/remote refetches the queries of remote functions.
pushState, replaceState shallow routing needs page.state, which the device doesn't have.
snapshot screens aren't restored from a history. The router saves its stacks itself (Navigation state).

The error reads `beforeNavigate` is not available on the device yet (expo-svelte) and then why. It is thrown when the function is called. beforeNavigate, afterNavigate, onNavigate and snapshot are called while a component initialises, so a screen that calls one fails to render with that message.

Page state

page from $app/state is a reactive object, like SvelteKit's, and it describes the screen the user sees now: the deepest one through the stacks, tabs and modals of the app. A tab switch, a push, a modal and a back each change it, and a $derived or $effect that reads it runs again. It works in any component and in any module, not only below a navigator, and before the app has a router it is the page of nothing (url is /, params is {}, route.id is null).

On the web there is one page at a time, so every component can read its own data from page. A phone keeps the screens below the top one mounted, so page is the top screen's wherever it is read: a screen that is covered by another one and reads page.params.id sees the id of the screen on top of it, and it changes when that screen opens. A screen reads its own data from the params and url props that SvelteKit gives a page, which are its own however many screens are above it. Use page for what concerns the whole app, such as highlighting the current tab in a bar, below, or reporting the screen to analytics.

src/routes/posts/[id]/+mobile.svelte
<script lang="ts">
	let { params }: { params: { id: string } } = $props();
</script>

<p>Post {params.id}</p>
src/lib/TabBar.svelte
<script lang="ts">
	import { page } from '$app/state';

	const tabs = [
		{ href: '/home', label: 'Home' },
		{ href: '/inbox', label: 'Inbox' }
	];
</script>

{#each tabs as tab (tab.href)}
	<a href={tab.href} aria-current={page.url.pathname.startsWith(tab.href) ? 'page' : undefined}>{tab.label}</a>
{/each}
Property On the device
url The URL of the screen, on the origin https://native.invalid (a native screen has no real one), the same URL useRouter().current.url has.
params The parameters of the screen's route: { slug: 'acme', id: '7' }.
route.id The id of the route, as SvelteKit writes it: the directory under src/routes, groups included, with a slash in front: /(app)/posts/[id]. The first screen is /.
status 200.
data, state {}. A screen has no load function and no page.state.
form, error, shallow null.

navigating has SvelteKit's shape for "no navigation": from, to, type, willUnload, delta and complete are all null. The router puts a screen on the stack in one step and has no navigation in flight to report, so navigating never says anything else.

updated is SvelteKit's { current, check() }, backed by the library's over-the-air updates. updated.current is true once an update is waiting for the next start: a check found one (updated.check(), checkForUpdateAsync), or one was downloaded (fetchUpdateAsync, or the check at launch), and it stays true until the app restarts on it. await updated.check() asks the server and resolves true when an update is waiting. It never rejects: a check that fails (the phone is offline) logs a warning and resolves false. In a build with updates off, a development build, current is false and check() resolves false without a request.

svelte
<script lang="ts">
	import { updated } from '$app/state';
	import { reloadAsync } from 'expo-svelte/updates';
</script>

{#if updated.current}
	<button onclick={() => reloadAsync()}>Update available: restart</button>
{/if}

Environment and mobile

$app/env is where SvelteKit 3 keeps browser, dev, building and version. SvelteKit 3 deprecates the old name, $app/environment; both resolve to the same module on the device, and both work on the web. The library adds mobile.

Export On the device In the web build
mobile true false
browser false: the device is not a browser SvelteKit's
dev __DEV__: a development build, served by Metro SvelteKit's
building false SvelteKit's
version the version of the app config (app.json, app.config.ts), as expo-constants reads it from the config embedded in the build, or '' when the build has none the version.name of SvelteKit's config

mobile is for code the web and the device share, where one of them should do something the other shouldn't:

src/lib/Feed.svelte
<script lang="ts">
	import { mobile } from '$app/env';

	let { items }: { items: string[] } = $props();

	// A phone draws fewer rows at a time.
	const visible = $derived(items.slice(0, mobile ? 20 : 100));
</script>

{#if mobile}
	<p>Tap an item to open it.</p>
{:else}
	<p>Click an item to open it.</p>
{/if}

<ul>
	{#each visible as item (item)}
		<li>{item}</li>
	{/each}
</ul>

The web side is the Vite plugin: expoSvelte() in vite.config.ts answers an import of $app/env (or $app/environment) with SvelteKit's own module plus export const mobile = false, in vite dev, in the client build and in the server build. Where the bundler can see the constant, as it does in a production build, the branch for the other platform is left out of the bundle. The flag does not take out an import that the other platform can't resolve. A file that imports a native library is a +mobile.svelte file, or is imported only by one: the web build leaves those out, and they need no flag.

browser is false on the device even though Svelte's runtime believes it runs in a browser (it reads esm-env, which stays as it is): a library that guards the DOM with if (browser) then skips it.

Paths

resolve from $app/paths builds the path of a route from its id and its parameters, as in SvelteKit, with an empty base path:

ts
import { resolve } from '$app/paths';

resolve('/posts/[id]', { id: 42 }); // '/posts/42'
resolve('/[[lang]]/about', {}); // '/about'
resolve('/docs/[...rest]', { rest: 'a/b' }); // '/docs/a/b'
resolve('/(app)/settings'); // '/settings'
resolve('posts/42'); // '/posts/42'

An optional parameter ([[lang]]) is left out when it is missing or empty, and a rest parameter ([...rest]) is any number of segments. A group ((app)) adds nothing to the path, an escape such as [x+2f] is the character it stands for, and a search or hash after a route id stays. A matcher ([id=integer]) names the parameter and checks nothing, since a native route has no src/params. A route id that has a parameter and is given none throws, as does a parameter that is missing, that starts or ends with /, or that isn't a string, number, boolean or bigint.

match(url) is the other way round: it resolves with { id, params } for the route of the path, or null when no screen has it. It rejects before the app has created its router.

asset(file) gives /file, SvelteKit's path with no base. A device has no static directory, so no element can load that path: use an import for an image of the project, or a full URL. base and assets, which SvelteKit 3 no longer exports, are '' for the code and libraries that still import them.

Motion

Spring, Tween, spring, tweened and prefersReducedMotion from svelte/motion are Svelte's own. The first four run on requestAnimationFrame, which React Native has. prefersReducedMotion is a MediaQuery of (prefers-reduced-motion: reduce), so prefersReducedMotion.current is the system's setting (Reduce Motion on iOS; animations turned off on Android) and is reactive like on the web: a template, $derived or $effect that reads it runs again when the setting changes. It is false for the moment before the system answers, which is shortly after the app starts.

svelte
<script lang="ts">
	import { Tween, prefersReducedMotion } from 'svelte/motion';

	const progress = new Tween(0, { duration: prefersReducedMotion.current ? 0 : 400 });
</script>

Svelte builds prefersReducedMotion when svelte/motion loads, and it calls window.matchMedia then. The app's entry installs the library's matchMedia before any screen's code is loaded, so there is nothing to do.

Media queries

React Native has no window.matchMedia, which Svelte's MediaQuery and a lot of code shared with the web call. The library adds one, so both work on the device. MediaQuery from svelte/reactivity is Svelte's own: current is the answer, and a template, $derived or $effect that reads it runs again when the answer changes.

src/lib/Layout.svelte
<script lang="ts">
	import { MediaQuery } from 'svelte/reactivity';

	const wide = new MediaQuery('(min-width: 600px)');
	const portrait = new MediaQuery('(orientation: portrait)');
	const dark = new MediaQuery('(prefers-color-scheme: dark)');
</script>

<p>{wide.current ? 'Wide' : 'Narrow'}, {portrait.current ? 'portrait' : 'landscape'}, {dark.current ? 'dark' : 'light'}</p>

window.matchMedia(query) is the browser's: a MediaQueryList with matches (read from the system each time), media (the query as a browser writes it: lower case, (min-width: 600px)), onchange, addEventListener('change', listener, { once, signal }) and removeEventListener, the older addListener and removeListener, and dispatchEvent. A change event has matches and media, and comes only when the answer flips: a window that gets wider while the query still matches says nothing. A list listens to the system while it has a listener and not before or after, so a MediaQuery that no effect reads costs nothing.

The queries are the browser's: a comma is or, and not, only, and, or and parentheses work as in CSS, as does the range syntax: (width >= 600px), (400px <= width < 700px). The media types all and screen match, and print and every other type don't. The features, and what each reads on the device:

Feature On the device
width, height (min- and max-) The window's size in points (dp, the px of CSS): Dimensions' window. It changes when the device turns, a foldable opens, or the window is split. em and rem are 16px; pt, pc, in, cm, mm and q are converted; vw, vh, vmin and vmax are percents of the window. A unitless 0 is allowed, and so is a negative length (it compares).
device-width, device-height (min- and max-), device-aspect-ratio The screen's size, Dimensions' screen: the window and the bars.
orientation portrait when the window is at least as tall as it is wide, landscape otherwise.
aspect-ratio (min- and max-) The window's width over its height, written 16/9 or 16 / 9.
resolution (min- and max-), -webkit-device-pixel-ratio (-webkit-min- and -webkit-max-) The window's pixel ratio, PixelRatio.get(): 2 is 2dppx, 2x, 192dpi and -webkit-device-pixel-ratio: 2.
prefers-color-scheme dark or light, from Appearance; a system that reports none is light. Appearance.setColorScheme overrides it.
prefers-reduced-motion reduce when the system's Reduce Motion is on (Android: animations turned off), from AccessibilityInfo. React Native answers that question asynchronously, so a query made before the answer is no-preference, and its change event comes when the answer is reduce.
prefers-contrast more when iOS's Increase Contrast (darker system colors) or Android's high contrast text is on, from AccessibilityInfo; no-preference otherwise. less and custom never match. It answers like prefers-reduced-motion.
prefers-reduced-transparency reduce when iOS's Reduce Transparency is on, from AccessibilityInfo; no-preference on Android, which has no such setting. It answers like prefers-reduced-motion.
inverted-colors inverted when the system's color inversion is on (iOS Smart Invert, Android color inversion), from AccessibilityInfo; none otherwise. It answers like prefers-reduced-motion.
forced-colors none: the app's colors are never forced.
update fast: the screen redraws at once.
scripting enabled.
color-gamut srgb: React Native cannot say that a display shows more, so p3 and rec2020 do not match.
hover, any-hover none: a phone has no hover.
pointer, any-pointer coarse: a finger.
display-mode standalone: the app is not in a browser.
color (min- and max-) 8, bits per color component.

A feature written alone, (hover), (color), (prefers-reduced-motion), is true when its value is not none, no-preference or zero.

What the device does not know is not an error, and it does not make the whole query false. As in a browser that follows Media Queries 4, a feature that is not in the table (monochrome, dynamic-range, ...), or a value it does not take ((min-width: red), (hover: sideways)), is unknown inside a condition: unknown is false on its own, and not leaves it unknown, so not (monochrome) is false too. But and is false when any part is false, and or is true when any part is true, so (monochrome) or (min-width: 600px) is what the width says, and (monochrome) and (min-width: 600px) is false. The query matches only when it is true. A query that does not parse ((min-width: 600px, (), screen and) is not all; in a comma-separated list the other queries still decide. media says not all for a query that can never be true because of what it does not know (matchMedia('(monochrome)').media === 'not all', which is how a page tests for support), and keeps the text of one the known parts can decide. Nothing throws.

The window and the scheme are the same values as windowSize and colorScheme (Platform APIs). Use those for a number or a scheme; use a media query for code shared with the web, or for a condition that is more than one comparison.

Not available

An import of one of these fails the Metro build, naming the module and why:

Module Why
$app/forms Forms submit to a SvelteKit server's actions. Use a remote function's form (Loading data).
$app/stores SvelteKit 3 removed the stores. Use page from $app/state.
$app/manifest, $app/service-worker They describe the web build's files, and a phone has no service worker.
$app/env/public The app has no SvelteKit environment. Read what it needs from the app config's extra with expo-constants.
$app/server, $app/env/private, $env/*/private They are server-only: Server-only import in native bundle. Code that runs on the server stays on it, in .server.ts files and remote functions.

The same goes for the files SvelteKit runs on the server or in the browser only, +page.js, +page.server.js, +server.js and +error.svelte: they have no counterpart on the device (Routing).

Type to search the guide.