{"record":{"id":"7f03a61ccf8176c2","repo":"sveltejs/kit","slug":"the-app-service-worker-module-can-only-be-impor","errorCode":null,"errorMessage":"The `$app/service-worker` module can only be imported into a service worker","messagePattern":"The `\\$app/service-worker` module can only be imported into a service worker","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/kit/src/runtime/app/service-worker/index.js","lineNumber":22,"sourceCode":"\nimport { DEV } from 'esm-env';\n\n/**\n * The execution context of a service worker. This export exists to make it easier to\n * use service workers with the correct types, provided the importing module is governed\n * by a `tsconfig.json` that extends [`$app/tsconfig/service-worker`](https://svelte.dev/docs/kit/$app-tsconfig-service-worker).\n *\n */\nexport const self = /** @type {ServiceWorkerGlobalScope} */ (\n\t/** @type {unknown} */ (globalThis.self)\n);\n\nif (DEV) {\n\tif (\n\t\ttypeof ServiceWorkerGlobalScope === 'undefined' ||\n\t\t!(self instanceof ServiceWorkerGlobalScope)\n\t) {\n\t\tthrow new Error('The `$app/service-worker` module can only be imported into a service worker');\n\t}\n}\n","sourceCodeStart":4,"sourceCodeEnd":25,"githubUrl":"https://github.com/sveltejs/kit/blob/03f1687fe612ce3d2d9131139b5b188d9cf90c64/packages/kit/src/runtime/app/service-worker/index.js#L4-L25","documentation":"In development, importing `$app/service-worker` from anywhere other than an actual service worker global scope throws immediately. The module exposes build assets and paths that only make sense inside a service worker. This is a dev-time guard against accidentally bundling service-worker-only code into the app or server.","triggerScenarios":"Importing `$app/service-worker` in a component, `load` function, or server module; a shared module that the service worker imports also being imported by app code; running tests in a non-ServiceWorkerGlobalScope environment with DEV true.","commonSituations":"Moving shared constants into a file that imports `build`, `files`, or `version` from `$app/service-worker`; importing the service worker source into a unit test; misconfigured bundler entry points.","solutions":["Ensure `$app/service-worker` is only imported from the `src/service-worker.js` entry","Extract shared values (e.g. cache names) into a separate module imported by both sides, without touching `$app/service-worker` in app code","Mock or exclude the module in tests (e.g. vi.mock('$app/service-worker'))"],"exampleFix":"// before (shared.js, imported by app)\nimport { version } from '$app/service-worker';\nexport const CACHE = `cache-${version}`;\n// after (shared.js)\nexport const CACHE_PREFIX = 'cache';\n// service-worker.js\nimport { version } from '$app/service-worker';\nimport { CACHE_PREFIX } from './shared';\nconst CACHE = `${CACHE_PREFIX}-${version}`;","handlingStrategy":"type-guard","validationCode":"if (typeof ServiceWorkerGlobalScope !== 'undefined' && self instanceof ServiceWorkerGlobalScope) {\n  import('$app/service-worker').then(initServiceWorkerLogic);\n}","typeGuard":"const inServiceWorker = typeof ServiceWorkerGlobalScope !== 'undefined' && self instanceof ServiceWorkerGlobalScope;","tryCatchPattern":"try {\n  const sw = await import('$app/service-worker');\n  useAssets(sw);\n} catch (e) {\n  if (e.message.includes('only be imported into a service worker')) {\n    console.warn('$app/service-worker used outside a service worker; skipping');\n  } else throw e;\n}","preventionTips":["Only import $app/service-worker from src/service-worker.js","Keep shared modules free of $app/* service-worker imports","Mock the module in unit tests and non-SW environments"],"tags":["service-worker","dev-guard","imports"],"backgroundTag":"wrong-scope-import","analyzedSha":"03f1687fe612ce3d2d9131139b5b188d9cf90c64","analyzedAt":"2026-09-02T02:01:50.504Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}