{"record":{"id":"7a3725dfacd6a466","repo":"withastro/astro","slug":"astro-components-cannot-be-used-in-the-browser-tr","errorCode":null,"errorMessage":"Astro components cannot be used in the browser.\nTried to render \"${filename}\".","messagePattern":"Astro components cannot be used in the browser\\.\nTried to render \"(.+?)\"\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/astro/src/vite-plugin-astro/index.ts","lineNumber":273,"sourceCode":"\t\t\t\t\t\texclude: [specialQueriesRE, /(?:\\?|&)astro(?:&|=|$)/],\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t\tasync handler(source, id) {\n\t\t\t\t\tconst parsedId = parseAstroRequest(id);\n\n\t\t\t\t\tif (!parsedId.filename.endsWith('.astro')) {\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\n\t\t\t\t\tconst filename = normalizePath(parsedId.filename);\n\n\t\t\t\t\t// If an Astro component is imported in code used on the client, we return an empty\n\t\t\t\t\t// module so that Vite doesn’t bundle the server-side Astro code for the client.\n\t\t\t\t\tif (this.environment.name === ASTRO_VITE_ENVIRONMENT_NAMES.client) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcode: `export default import.meta.env.DEV\n\t\t\t\t\t\t\t\t\t? () => {\n\t\t\t\t\t\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\t\t\t\t\t\t'Astro components cannot be used in the browser.\\\\nTried to render \"${filename}\".'\n\t\t\t\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t\t: {};`,\n\t\t\t\t\t\t\tmoduleType: 'ts',\n\t\t\t\t\t\t\tmeta: { vite: { lang: 'ts' } },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\n\t\t\t\t\tconst transformResult = await compile(source, filename);\n\n\t\t\t\t\tconst astroMetadata: AstroPluginMetadata['astro'] = {\n\t\t\t\t\t\t// Remove Astro components that have been mistakenly given client directives\n\t\t\t\t\t\t// We'll warn the user about this later, but for now we'll prevent them from breaking the build\n\t\t\t\t\t\tclientOnlyComponents: transformResult.clientOnlyComponents.filter(notAstroComponent),\n\t\t\t\t\t\thydratedComponents: transformResult.hydratedComponents.filter(notAstroComponent),\n\t\t\t\t\t\tserverComponents: transformResult.serverComponents,\n\t\t\t\t\t\tscripts: transformResult.scripts,","sourceCodeStart":255,"sourceCodeEnd":291,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/vite-plugin-astro/index.ts#L255-L291","documentation":"Thrown at runtime (in dev) when an Astro component (`.astro`) is imported into client-side code. Astro components are server-rendered; they cannot run in the browser. The plugin detects imports of `.astro` files in the client environment and returns a stub module that throws this error when the stub default export is invoked in dev, or an empty object in production builds.","triggerScenarios":"Importing a `.astro` component from a `<script>` block (client-side), a client-side `.ts`/`.js` file, or any module resolved by the `client` Vite environment. The throw happens when the default export (a render function) is called in dev.","commonSituations":"Trying to use an Astro component as a client-side widget or web component. Importing a shared `.astro` layout/component from a client script for its types or constants. Confusing Astro components (server-only) with framework components (React/Vue/Svelte) which can hydrate.","solutions":["Move the shared logic/constants into a plain `.ts` or `.js` module and import that from both the component and the client script.","If you need client-side interactivity, use a framework component (React/Vue/Svelte/Solid) with `client:*` directives instead of an `.astro` file.","If you only needed types, import the type via `import type` (erased at runtime) or define types in a separate `.d.ts`."],"exampleFix":"// before — client.ts\nimport MyComponent from '../components/MyComponent.astro';\n\n// after\nimport { sharedConstants } from '../utils/shared.ts';","handlingStrategy":"type-guard","validationCode":"// Ensure no .astro import appears in client-resolved modules.\n// Run: grep -rn \"from '.*\\\\.astro'\" src/ then verify each importer is server-only.","typeGuard":"// ESLint rule of thumb: disallow importing .astro from files under src/scripts or client entrypoints.\n// no-restricted-syntax: reject ImportDeclaration whose source ends with .astro in client contexts.","tryCatchPattern":null,"preventionTips":["Never import .astro files from client scripts; extract shared logic to .ts.","Use framework components (React/Vue) for client interactivity, not .astro.","Add an ESLint rule banning .astro imports outside of other .astro files."],"tags":["astro-component","client-side","bundler","ssr"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}