Script Modules: Além das Instâncias de Componentes

Todo componente Svelte que você escreveu até agora possui um script de instância—o bloco <script> que é executado para cada instância do componente. Mas e se você precisar de um código que seja executado uma única vez para o tipo de componente inteiro, e não por instância? E se você quiser compartilhar estado ou utilitários entre todas as instâncias de um componente?

É aí que entram os script modules—o mecanismo do Svelte para compartilhamento de código no nível do componente. No Svelte 5, a sintaxe evoluiu de <script context="module"> para o mais limpo <script module>, mas o conceito continua poderoso: código que é executado uma única vez quando o módulo do componente é carregado, compartilhado entre todas as instâncias.

Este tutorial explora os script modules de forma abrangente: sua sintaxe, casos de uso, limitações e como se integram ao sistema reativo do Svelte 5.

Capítulo 1: Entendendo os Script Modules

1.1 Scripts de Instância vs. Scripts de Módulo

Scripts de Instância (<script>):

São executados uma vez por instância do componente
Têm acesso a props, estado e ciclo de vida
Podem ser reativos com runes como $state, $derived, $effect

Scripts de Módulo (<script module>):

São executados uma única vez quando o módulo do componente é carregado pela primeira vez
Compartilhados entre todas as instâncias do componente
Não podem acessar dados específicos de instância (props, estado)
São executados no escopo do módulo, não no escopo do componente

<!-- Component.svelte -->
<script module>
	// This runs once for the entire component type
	console.log('Component module loaded')

	// Shared across all instances
	let instanceCount = 0

	export function getInstanceCount() {
		return instanceCount
	}
</script>

<script>
	// This runs for each component instance
	console.log('New instance created')

	// Access module-level function
	const count = getInstanceCount()
</script>

1.2 O Modelo de Execução

Os scripts de módulo são executados durante a fase de carregamento do módulo, antes de qualquer instância do componente ser criada:

<!-- Logger.svelte -->
<script module>
	// ✅ Runs immediately when module loads
	console.log('Logger module initialized')

	// Module-level state
	let logHistory = []

	export function log(message) {
		logHistory.push({ message, timestamp: Date.now() })
		console.log(`[${new Date().toISOString()}] ${message}`)
	}

	export function getLogHistory() {
		return [...logHistory]
	}
</script>

<script>
	let { componentName } = $props()

	// Use module function
	log(`${componentName} component mounted`)
</script>

1.3 Regras de Acesso e Ciclo de Vida SSR

Módulo → Instância: Declarações no script de módulo estão disponíveis para o script de instância e para a marcação, pois compartilham o mesmo escopo de módulo compilado. Elas não são reativas ao estado da instância—trate-as como variáveis comuns no nível do módulo.
Instância → Módulo: Scripts de módulo não podem ver valores exclusivos de instância (props, runes), pois esses são criados por instância.
Considerações sobre servidor: No SSR do SvelteKit, o estado do módulo é compartilhado entre requisições, a menos que você o isole explicitamente (por exemplo, criando um estado novo dentro de um módulo com escopo de requisição). Evite armazenar dados por requisição no escopo do módulo.
Guardas de ambiente: Scripts de módulo são executados onde quer que o módulo do componente seja carregado. Use import { browser } from '$app/environment' (SvelteKit) ou verificações de funcionalidade antes de acessar window/document.

Capítulo 2: Casos de Uso Comuns para Script Modules

2.1 Utilitários e Constantes Compartilhados

Scripts de módulo se destacam no fornecimento de utilitários que não precisam de estado por instância:

<!-- DateUtils.svelte -->
<script module>
	// Constants shared across instances
	export const DATE_FORMATS = {
		SHORT: 'MM/dd/yyyy',
		LONG: 'MMMM dd, yyyy',
		ISO: 'yyyy-MM-dd'
	}

	// Utility functions
	export function formatDate(date, format = DATE_FORMATS.SHORT) {
		// Implementation...
		return new Intl.DateTimeFormat('en-US').format(date)
	}

	export function isWeekend(date) {
		const day = date.getDay()
		return day === 0 || day === 6
	}

	export function addDays(date, days) {
		const result = new Date(date)
		result.setDate(result.getDate() + days)
		return result
	}
</script>

<script>
	let { date } = $props()

	// Use shared utilities
	$: formatted = formatDate(date)
	$: isWeekendDay = isWeekend(date)
</script>

2.2 Rastreamento de Instâncias e Analytics

Rastreie o uso de componentes em toda a sua aplicação:

<!-- Button.svelte -->
<script module>
	let clickCount = 0
	let instances = new Set()

	export function recordClick(componentId) {
		clickCount++
		console.log(`Button clicked (total: ${clickCount})`)
	}

	export function registerInstance(id) {
		instances.add(id)
	}

	export function unregisterInstance(id) {
		instances.delete(id)
	}

	export function getStats() {
		return {
			totalClicks: clickCount,
			activeInstances: instances.size
		}
	}
</script>

<script>
	let { id, children, ...props } = $props()

	// Register this instance
	$effect(() => {
		registerInstance(id)
		return () => unregisterInstance(id)
	})

	function handleClick() {
		recordClick(id)
		// ... other click logic
	}
</script>

<button onclick={handleClick} {...props}>
	{@render children?.()}
</button>

2.3 Gerenciamento de Estado Global do Componente

Para estado global específico do componente que não pertence a uma store:

<!-- ThemeProvider.svelte -->
<script module>
	// Global theme state for all ThemeProvider instances
	let currentTheme = 'light'
	let subscribers = new Set()

	export function setTheme(theme) {
		currentTheme = theme
		// Notify all subscribers
		subscribers.forEach((callback) => callback(theme))
	}

	export function getTheme() {
		return currentTheme
	}

	export function subscribeToTheme(callback) {
		subscribers.add(callback)
		return () => subscribers.delete(callback)
	}
</script>

<script>
	let { children } = $props()

	// Subscribe to theme changes
	$effect(() => {
		const unsubscribe = subscribeToTheme((theme) => {
			// Update component state
			document.documentElement.setAttribute('data-theme', theme)
		})

		return unsubscribe
	})
</script>

<div class="theme-provider">
	{@render children?.()}
</div>

2.4 Padrão de Registro de Componentes

Crie sistemas de componentes descobríveis:

<!-- ComponentRegistry.svelte -->
<script module>
	const registry = new Map()

	export function registerComponent(name, component) {
		registry.set(name, component)
		console.log(`Registered component: ${name}`)
	}

	export function getComponent(name) {
		return registry.get(name)
	}

	export function getAllComponents() {
		return Array.from(registry.entries())
	}

	export function unregisterComponent(name) {
		return registry.delete(name)
	}
</script>

<!-- Usage in other components -->
<script>
	import ComponentRegistry from './ComponentRegistry.svelte'

	// Register this component
	$effect(() => {
		ComponentRegistry.registerComponent('MyComponent', MyComponent)
		return () => ComponentRegistry.unregisterComponent('MyComponent')
	})
</script>

Capítulo 3: Exportando Snippets de Scripts de Módulo

O Svelte 5.5.0 introduziu a capacidade de exportar snippets de scripts de módulo, habilitando padrões poderosos de composição de componentes.

3.1 Exportação Básica de Snippet

<!-- FormSnippets.svelte -->
<script module>
	export { inputField, selectField, checkboxField }
</script>

{#snippet inputField(label, value, type = 'text', ...attrs)}
	<div class="form-field">
		<label>{label}</label>
		<input {type} bind:value {...attrs} />
	</div>
{/snippet}

{#snippet selectField(label, value, options, ...attrs)}
	<div class="form-field">
		<label>{label}</label>
		<select bind:value {...attrs}>
			{#each options as option}
				<option value={option.value}>{option.label}</option>
			{/each}
		</select>
	</div>
{/snippet}

{#snippet checkboxField(label, checked, ...attrs)}
	<div class="form-field">
		<label>
			<input type="checkbox" bind:checked {...attrs} />
			{label}
		</label>
	</div>
{/snippet}

3.2 Usando Snippets Exportados

<!-- ContactForm.svelte -->
<script>
	import { inputField, selectField, checkboxField } from './FormSnippets.svelte'

	let formData = $state({
		name: '',
		email: '',
		country: '',
		newsletter: false
	})

	const countries = [
		{ value: 'us', label: 'United States' },
		{ value: 'ca', label: 'Canada' },
		{ value: 'uk', label: 'United Kingdom' }
	]
</script>

<form>
	{@render inputField('Name', formData.name, 'text', { required: true })}
	{@render inputField('Email', formData.email, 'email', { required: true })}
	{@render selectField('Country', formData.country, countries)}
	{@render checkboxField('Subscribe to newsletter', formData.newsletter)}
</form>

3.3 Limitações dos Snippets Exportados

Snippets exportados possuem regras rígidas de escopo:

<!-- ❌ This will NOT work -->
<script>
	let instanceVar = "can't access this";
</script>

<script module>
	export { brokenSnippet };
</script>

{#snippet brokenSnippet()}
	<!-- Error: Cannot access instance variables -->
	<p>{instanceVar}</p>
{/snippet}

<!-- ✅ This WILL work -->
<script module>
	const MODULE_CONSTANT = "this is fine";
	export { workingSnippet };
</script>

{#snippet workingSnippet()}
	<p>{MODULE_CONSTANT}</p>
{/snippet}

Capítulo 4: Padrões Avançados e Boas Práticas

4.1 Estado Reativo no Nível do Módulo

Embora scripts de módulo não possam usar runes diretamente, você pode criar padrões reativos:

<!-- ReactiveModule.svelte -->
<script module>
	// Module-level reactive state using custom events
	let _value = 'initial'
	const listeners = new Set()

	export function getValue() {
		return _value
	}

	export function setValue(newValue) {
		_value = newValue
		// Notify listeners
		listeners.forEach((listener) => listener(newValue))
	}

	export function subscribe(listener) {
		listeners.add(listener)
		return () => listeners.delete(listener)
	}
</script>

<script>
	let localValue = $state('')

	// Subscribe to module changes
	$effect(() => {
		const unsubscribe = subscribe((newValue) => {
			localValue = newValue
		})
		return unsubscribe
	})
</script>

4.2 Combinando Scripts de Módulo com Stores

Para estados compartilhados complexos, combine scripts de módulo com stores do Svelte:

<!-- UserPreferences.svelte -->
<script module>
	import { writable } from 'svelte/store'

	// Module-level store
	export const userPreferences = writable({
		theme: 'light',
		language: 'en',
		notifications: true
	})

	// Utility functions
	export function updatePreference(key, value) {
		userPreferences.update((prefs) => ({ ...prefs, [key]: value }))
	}

	export function resetPreferences() {
		userPreferences.set({
			theme: 'light',
			language: 'en',
			notifications: true
		})
	}
</script>

<script>
	import { userPreferences } from './UserPreferences.svelte'

	// Use in component
	let prefs = $state()
	userPreferences.subscribe((value) => (prefs = value))
</script>

4.3 Testando Scripts de Módulo

Scripts de módulo podem ser desafiadores de testar devido à sua natureza compartilhada:

// ModuleScript.test.js
import { getInstanceCount, recordClick } from './Button.svelte'

// Reset module state between tests
beforeEach(() => {
	// If your module exposes reset functions, use them
	// Otherwise, you may need to re-import or use a different strategy
})

// Test module functions
test('tracks clicks across instances', () => {
	expect(getInstanceCount()).toBe(0)
	recordClick('test-id')
	expect(getInstanceCount()).toBe(1)
})

Capítulo 5: Migração do Svelte 4

5.1 Mudanças de Sintaxe

<!-- Svelte 4 -->
<script context="module">
	export const sharedValue = 'hello';
</script>

<!-- Svelte 5 -->
<script module>
	export const sharedValue = 'hello';
</script>

5.2 Mudanças Comportamentais

Scripts de módulo agora são executados em modo estrito
Melhor suporte a tree-shaking
Mensagens de erro aprimoradas
Capacidade de exportação de snippets (nova no 5.5.0)

Conclusão: Quando Usar Scripts de Módulo

Scripts de módulo são poderosos, mas devem ser usados com critério:

Use scripts de módulo para:

Utilitários e constantes compartilhados
Analytics e rastreamento de componentes
Estado global de componentes
Bibliotecas de snippets
Registros de componentes

Não use scripts de módulo para:

Lógica específica de instância
Estado reativo que varia por componente
Efeitos colaterais que devem ser executados por instância

Dominar scripts de módulo desbloqueia novos padrões para comunicação entre componentes e organização de código no Svelte 5. Eles preenchem a lacuna entre instâncias individuais de componentes e as preocupações em nível de aplicação, tornando seus componentes mais composáveis e fáceis de manter.