urlImports

Core Idea

Feature experimental que permite importar módulos diretamente de servidores externos (URLs) em vez de só do disco local, com um lockfile (next.lock) garantindo builds reproduzíveis e uma allowlist explícita de domínios confiáveis.

Key Concepts

• experimental.urlImports: array de prefixos de URL permitidos; qualquer import de URL precisa começar com um desses prefixos.
• Security model: allowlist explícita de domínios é a primeira camada; planejado (na época da doc) restringir execução ao sandbox do Edge Runtime.
• Lockfile next.lock: diretório com lockfile e assets baixados; deve ser commitado no Git, nunca no .gitignore.
• Comportamento dev vs build: next dev baixa e adiciona novos URL imports descobertos ao lockfile; next build usa somente o lockfile (nenhuma rede necessária, exceto para recursos no-cache).

Code Examples

module.exports = {
  experimental: {
    urlImports: ['https://example.com/assets/', 'https://cdn.skypack.dev'],
  },
}

• O que demonstra: allowlist de dois prefixos de domínio para permitir imports remotos.

import confetti from 'https://cdn.skypack.dev/canvas-confetti'
import { useEffect } from 'react'

export default () => {
  useEffect(() => {
    confetti()
  })
  return <p>Hello</p>
}

• O que demonstra: import de uma lib inteira direto de um CDN (Skypack), sem instalar via npm.

import Image from 'next/image'
import logo from 'https://example.com/assets/logo.png'

export default () => (
  <div>
    <Image src={logo} placeholder="blur" />
  </div>
)

• O que demonstra: URL import funciona também com assets estáticos (imagem) consumidos por next/image.

Anti-patterns

• Adicionar .gitignore ao diretório next.lock: quebra a reprodutibilidade do build; ele precisa estar versionado.
• Confiar em domínios não verificados: a doc alerta para só usar domínios em que você confia baixar e executar código na sua máquina.

Key Takeaways

1. URL imports funcionam em qualquer lugar que imports normais de pacote funcionam (componentes, CSS via url(), asset imports via new URL(...)).
2. next build nunca faz rede a menos que o recurso tenha Cache-Control: no-cache, tudo vem do lockfile.
3. Feature experimental e de segurança sensível: o modelo de segurança ainda estava evoluindo (rumo ao Edge Runtime sandbox) no momento da doc.

Connects To

• Edge Runtime: destino planejado para execução sandboxed de URL imports.