Gosto de escrever Javascript sem um sistema de compilação e pela milionésima vez ontem me deparei com um problema em que precisava descobrir como importar uma biblioteca Javascript em meu código sem usar um sistema de compilação, e demorou SEMPRE para descobrir como importá-lo porque as instruções de configuração da biblioteca assumem que você está usando um sistema de compilação.

Felizmente, neste ponto, aprendi principalmente como navegar nessa situação e usar a biblioteca com sucesso ou decidir que é muito difícil e mudar para uma biblioteca diferente, então aqui está o guia que eu gostaria de ter para importar bibliotecas Javascript anos atrás.

Vou falar apenas sobre o uso de bibliotecas Javacript no frontend e apenas sobre como usá-las em uma configuração sem sistema de compilação.

Neste post vou falar sobre:

1. os três principais tipos de arquivos Javascript que uma biblioteca pode fornecer (Módulos ES, o tipo de variável global “clássico” e CommonJS)
2. como descobrir quais tipos de arquivos uma biblioteca Javascript inclui em sua construção
3. maneiras de importar cada tipo de arquivo em seu código

os três tipos de arquivos Javascript

Existem 3 tipos básicos de arquivos Javascript que uma biblioteca pode fornecer:

1. o tipo “clássico” de arquivo que define uma variável global. Este é o tipo de arquivo que você pode simplesmente

   e então eu poderia usar a biblioteca com o global Chart variável de ambiente. Não poderia ser mais fácil. acabei de copiar chart.umd.js em meu repositório Git para que eu não precisasse me preocupar em usar o NPM ou os CDNs caindo ou algo assim.

   os arquivos de compilação nem sempre estão no dist diretório

   Muitas bibliotecas colocarão sua construção no dist diretório, mas nem sempre! A localização dos arquivos de construção é especificada no arquivo da biblioteca package.json.

   Por exemplo, aqui está um trecho do Chart.js package.json.

     "jsdelivr": "./dist/chart.umd.js",
     "unpkg": "./dist/chart.umd.js",
     "main": "./dist/chart.cjs",
     "module": "./dist/chart.js",
   

   Acho que isso quer dizer que se você quiser usar um Módulo ES (module) você deve usar dist/chart.jsmas os CDNs jsDelivr e unpkg devem usar ./dist/chart.umd.js. Eu acho main é para Node.

   chart.jsde package.json também diz "type": "module"que de acordo com esta documentação diz ao Node para tratar os arquivos como módulos ES por padrão. Acho que não nos diz especificamente quais arquivos são módulos ES e quais não são, mas nos diz que algo existe um módulo ES.

   biblioteca de exemplo 2: @atcute/oauth-browser-client

   @atcute/oauth-browser-client

   é uma biblioteca para fazer login no Bluesky com OAuth no navegador.

   Vamos ver que tipos de arquivos Javascript ele fornece em sua construção!

   $ npm install @atcute/oauth-browser-client
   $ cd node_modules/@atcute/oauth-browser-client/dist
   $ ls *js
   constants.js  dpop.js  environment.js  errors.js  index.js  resolvers.js
   

   Parece que o único arquivo raiz plausível aqui é index.jsque se parece com isto:

   export { configureOAuth } from './environment.js';
   export * from './errors.js';
   export * from './resolvers.js';
   

   Esse export sintaxe significa que é um Módulo ES. Isso significa que podemos usá-lo no navegador sem uma etapa de construção! Vamos ver como fazer isso.

   como usar um módulo ES com importmaps

   Usar um módulo ES não é tão fácil quanto adicionar um

   Fazer com que esses mapas de importação funcionem é bastante complicado. Sinto que deve haver uma ferramenta para gerá-los automaticamente, mas ainda não encontrei uma. Definitivamente, é possível escrever um script que gere automaticamente os importmaps usando o metarquivo do esbuild, mas não fiz isso e talvez haja uma maneira melhor.

   Decidi configurar importmaps ontem para fazer github.com/jvns/bsky-oauth-example funcionar, então há alguns exemplos de código nesse repositório.

   Além disso, alguém me indicou o download-esm de Simon Willison, que fará o download de um módulo ES e reescreverá as importações para apontar diretamente para os arquivos JS, para que você não precise de mapas de importação. Ainda não experimentei mas parece uma ótima ideia.

   problemas com importmaps: muitos arquivos

   Porém, tive alguns problemas ao usar importmaps no navegador – era necessário baixar dezenas de arquivos Javascript para carregar meu site, e meu servidor web em desenvolvimento não conseguia acompanhar por algum motivo. Continuei vendo os arquivos falharem ao carregar aleatoriamente e então tive que recarregar a página e esperar que desta vez eles tivessem sucesso.

   Não foi mais um problema quando implantei meu site em produção, então acho que foi um problema com meu ambiente de desenvolvimento local.

   Além disso, uma coisa um pouco irritante sobre os módulos ES em geral é que você precisa estar executando um servidor web para usá-los, tenho certeza de que isso é por um bom motivo, mas é mais fácil quando você pode simplesmente abrir seu index.html arquivo sem iniciar um servidor web.

   Por causa da coisa de “muitos arquivos”, acho que usar módulos ES com importmaps dessa forma não é tão atraente para mim, mas é bom saber que é possível.

   como usar um módulo ES sem importmaps

   Se o módulo ES não tiver dependências então é ainda mais fácil – você não precisa dos importmaps! Você pode apenas:

   • colocar

     e depois coloque isso script.js.

     import { BrowserOAuthClient } from "https://esm.sh/@atproto/oauth-client-browser@0.3.0"
     

     Parece que simplesmente funciona, o que é legal! É claro que isso ainda é uma espécie de sistema de compilação - é só que esm.sh está executando a compilação em vez de mim. Minhas principais preocupações com essa abordagem são:

     • Eu realmente não confio que CDNs continuem funcionando para sempre – geralmente gosto de copiar dependências em meu repositório para que elas não desapareçam por algum motivo no futuro.
     • Ouvi falar de alguns problemas com CDNs com comprometimento de segurança, o que me assusta.
     • Eu realmente não entendo o que esm.sh está fazendo.

     esbuild também pode converter módulos CommonJS em módulos ES

     Também aprendi que você também pode usar esbuild converter um módulo CommonJS em um módulo ES, embora existam algumas limitações – o import { BrowserOAuthClient } from sintaxe não funciona. Aqui está uma questão do github sobre isso.

     Eu acho que o esbuild abordagem é provavelmente mais atraente para mim do que a esm.sh abordagem porque é uma ferramenta que já tenho no meu computador, então confio mais nela. Ainda não experimentei muito isso.

     resumo dos três tipos de arquivos

     Aqui está um resumo dos três tipos de arquivos JS que você pode encontrar, opções de como usá-los e como identificá-los.

     Inutilmente um .js ou .min.js a extensão do arquivo pode ser qualquer uma dessas três opções, portanto, se o arquivo for something.js você precisa fazer mais trabalho de detetive para descobrir com o que está lidando.

     1. Arquivos JS “clássicos”
        • Como usar::
2. Módulos ES
   • Maneiras de usá-lo:
     • Se não houver dependências, basta import {whatever} from "./my-module.js" diretamente no seu código
     • Se houver dependências, crie um importmap e import {whatever} from "my-module"
     • Use esbuild ou qualquer empacotador de módulo ES
   • Maneiras de identificá-lo:
     • Procure um import ou export declaração. (não module.exports = ...isso é CommonJS)
     • Um .mjs extensão
     • talvez "type": "module" em package.json (embora não esteja claro para mim a qual arquivo exatamente isso se refere)
3. Módulos CommonJS
   • Maneiras de usá-lo:
     • Use https://esm.sh para convertê-lo em um módulo ES, como https://esm.sh/@atproto/oauth-client-browser@0.3.0
     • Use uma compilação de alguma forma (??)
   • Maneiras de identificá-lo:
     • Procurar require() ou module.exports = ... no código
     • UM .cjs extensão
     • talvez "type": "commonjs" em package.json (embora não esteja claro para mim a qual arquivo exatamente isso se refere)

é muito bom ter módulos ES padronizados

A principal diferença entre os módulos CommonJS e os módulos ES, na minha perspectiva, é que os módulos ES são, na verdade, um padrão. Isso me faz sentir muito mais confiante ao usá-los, porque os navegadores se comprometem para sempre com a compatibilidade com versões anteriores dos padrões da Web – se eu escrever algum código usando módulos ES hoje, posso ter certeza de que ainda funcionará da mesma maneira daqui a 15 anos.

Também me faz sentir melhor ao usar ferramentas como esbuild porque mesmo que o projeto esbuild morra, por estar implementando um padrão, parece provável que haverá outra ferramenta semelhante no futuro pela qual eu possa substituí-lo.

Muitas vezes quando falo sobre essas coisas recebo respostas como “Eu odeio javascript!!! Mas minha experiência é que existem muitas ferramentas excelentes para Javascript (acabei de aprender sobre https://esm.sh ontem, o que parece ótimo! Adoro esbuild!), e que se eu dedicar um tempo para aprender como as coisas funcionam, posso aproveitar algumas dessas ferramentas e tornar minha vida muito mais fácil.

Portanto, o objetivo deste post definitivamente não é reclamar do Javascript, é entender o cenário para que eu possa usar as ferramentas de uma maneira que me pareça boa.

perguntas que ainda tenho

Aqui estão algumas perguntas que ainda tenho. Adicionarei as respostas ao post se souber a resposta.

• Existe uma ferramenta que gera automaticamente mapas de importação para um módulo ES que configurei localmente? (aparentemente sim: jspm)
• Como posso converter um módulo CommonJS em um módulo ES no meu computador, da mesma forma que https://esm.sh faz? (aparentemente, o esbuild pode fazer isso, embora as exportações nomeadas não funcionem)
• Quando as pessoas normalmente constroem módulos CommonJS em código JS normal, qual código está fazendo isso? Obviamente, existem ferramentas como webpack, rollup, esbuild, etc, mas todas essas ferramentas implementam seus próprios analisadores JS/análise estática? Quantos analisadores JS existem por aí?
• Existe alguma maneira de agrupar um módulo ES em um único arquivo (como
  atcute-client.js), mas para que no navegador eu ainda possa importar vários caminhos diferentes desse arquivo (como ambos @atcute/client/lexicons e
  @atcute/client)?

todas as ferramentas

Aqui está uma lista de todas as ferramentas sobre as quais falamos nesta postagem:

Escrever esta postagem me fez pensar que, embora eu geralmente não queira ter uma compilação que execute toda vez que atualizo o projeto, talvez eu esteja disposto a realizar uma etapa de compilação (usando download-esm ou algo assim) que eu corro apenas uma vez
ao configurar o projeto e nunca mais executá-lo, exceto talvez se eu estiver atualizando minhas versões de dependência.

isso é tudo!

Obrigado ao Marco Rogers que me ensinou muitas coisas neste post. Provavelmente cometi alguns erros neste post e adoraria saber quais são – me avise no Bluesky ou Mastodon!