[@astrojs/alpinejs] entrypoint `${entrypoint}` does not expo

Error message

[@astrojs/alpinejs] entrypoint `${entrypoint}` does not export a default function. Check out https://docs.astro.build/en/guides/integrations-guide/alpinejs/#entrypoint.

What it means

The @astrojs/alpinejs integration's `entrypoint` option generates a shim that imports your entry module and calls its default export with the Alpine instance. If the module exports only named functions (no default), the shim's `'default' in mod` check fails and — in dev only — it logs this warning, meaning your Alpine plugins/directives never register.

Source

Thrown at packages/integrations/alpinejs/src/index.ts:80

				return resolvedVirtualModuleId;
			},
		},
		load: {
			filter: {
				id: new RegExp(`^${resolvedVirtualModuleId}$`),
			},
			handler() {
				if (entrypoint) {
					return `\
import * as mod from ${JSON.stringify(entrypoint)};
						
export const setup = (Alpine) => {
	if ('default' in mod) {
		mod.default(Alpine);
	} else {
		${
			!isBuild
				? `console.warn("[@astrojs/alpinejs] entrypoint \`" + ${JSON.stringify(
						entrypoint,
					)} + "\` does not export a default function. Check out https://docs.astro.build/en/guides/integrations-guide/alpinejs/#entrypoint.");`
				: ''
		}
	}
}`;
				}
				return `export const setup = () => {};`;
			},
		},
	};
}

export default function createPlugin(options?: Options): AstroIntegration {
	return {
		name: '@astrojs/alpinejs',
		hooks: {
			'astro:config:setup': ({ injectScript, updateConfig }) => {

View on GitHub (pinned to 52e6c34790)

Solutions

Change the entrypoint to default-export a function: `export default function (Alpine) { ... }`
Move all plugin/directive registration (Alpine.directive, Alpine.magic, Alpine.plugin) inside that default function
Verify the path passed to `entrypoint` resolves to the intended file (a wrong path fails earlier with module-not-found)

Example fix

// before  src/alpine.ts
export function setup(Alpine: any) {
  Alpine.magic('fmt', () => (v: number) => v.toFixed(2));
}

// after
export default function (Alpine: any) {
  Alpine.magic('fmt', () => (v: number) => v.toFixed(2));
}

Defensive patterns

Strategy: type-guard

Validate before calling

// Fail loudly at bootstrap instead of relying on the dev-only runtime warning
import * as entry from './src/alpine';
if (typeof entry.default !== 'function') {
  throw new Error('src/alpine must default-export a function that receives Alpine');
}

Type guard

const hasDefaultSetup = (mod: object): mod is { default: (Alpine: unknown) => void } =>
  'default' in mod && typeof (mod as { default?: unknown }).default === 'function';

Prevention

Treat the entrypoint contract as exactly one default-exported function taking Alpine
Add a unit/type test asserting typeof entry.default === 'function'
Check the browser console in dev right after configuring the entrypoint option

When it happens

Trigger: Configuring alpinejs({ entrypoint: './src/alpine' }) where that file has `export function setup(Alpine)` or other named exports but no `export default`. The warning appears in the browser console during `astro dev`; production builds skip it (but the setup still silently no-ops).

Common situations: Writing the Alpine setup as a named export out of habit; refactoring the entry file and dropping the default keyword; mixing ESM named-export style with an integration that requires the default-export contract.

Related errors

AI-assisted analysis of withastro/astro@52e6c34790 (2026-08-18). Data as JSON: /api/errors/0e49af4138cc27a1. Report an issue: GitHub.