Ao iniciar um novo projeto web onde JavaScript será usado, muitas vezes a primeira coisa que fazemos é configurar ferramentas de construção e desenvolvedor. Por exemplo, Vite, que é popular atualmente. Você pode não estar ciente de que ferramentas de construção complicadas não são necessárias para todos os projetos JavaScript (web). Na verdade, agora é mais fácil ficar sem do que nunca, como mostrarei neste artigo.

Crie um novo projeto com um arquivo index.html.

  
  
  
    
Hello world
  

Se você estiver usando o VS Code, instale a extensão Live Preview. Executá-lo. Este é um servidor de arquivos simples com recarga ao vivo. Você pode usar qualquer servidor de arquivos, Python vem com um integrado:

python3 -m http.server

Gosto do Live Preview porque ele atualiza automaticamente a página após fazer alterações em um arquivo.

Agora você deve conseguir acessar seu arquivo index.html no navegador e ver "Olá, mundo".

Em seguida, crie um arquivo index.js:

console.log("Hello world");

export {};

Inclua-o em seu index.html:

Abra o console do desenvolvedor em seu navegador. Se você vir "Olá, mundo", você sabe que ele está carregando corretamente.

Os navegadores agora suportam módulos ECMAScript. Você pode importar outros arquivos para seus efeitos colaterais:

import "./some-other-script.js";

ou para suas exportações

import { add, multiply } "./my-math-lib.js";

Muito legal, certo? Consulte o guia MDN acima para obter mais informações.

Pacotes

Você provavelmente não quer reinventar a roda, então seu projeto provavelmente usará alguns pacotes de terceiros. Isso não significa que agora você precisa começar a usar um gerenciador de pacotes.

Digamos que queremos usar superestrutura para validação de dados. Não podemos apenas carregar módulos de nosso próprio servidor de arquivos (local), mas de qualquer URL. esm.sh fornece módulos convenientemente para quase todos os pacotes disponíveis no npm.

Ao visitar https://esm.sh/superstruct você verá que será redirecionado para a versão mais recente. Você pode incluir este pacote da seguinte maneira em seu código:

import { assert } from "https://esm.sh/superstruct";

Se quiser estar seguro, você pode fixar as versões.

Tipos

Não sei sobre você, mas o TypeScript me estragou (e me deixou com preguiça). Escrever JavaScript simples sem a ajuda do verificador de tipo é como escrever na corda bamba. Felizmente, também não precisamos abrir mão da verificação de tipo.

É hora de eliminar o npm (mesmo que não enviemos nenhum código que ele forneça).

npm init --yes
npm install typescript

Você pode usar o compilador TypeScript em código JavaScript perfeitamente! Existe suporte de primeira classe para isso. Crie um jsconfig.json:

{
  "compilerOptions": {
    "strict": true,
    "checkJs": true,
    "allowJs": true,
    "noImplicitAny": true,
    "lib": ["ES2022", "DOM"],
    "module": "ES2022",
    "target": "ES2022"
  },
  "include": ["**/*.js"],
  "exclude": ["node_modules"]
}

Agora execute

npm run tsc --watch -p jsconfig.json

e comete um erro de tipo no seu código. O compilador TypeScript deve reclamar:

/** @type {number} **/
const num = "hello";

A propósito, o comentário que você vê acima é JSDoc. Você pode anotar seu JavaScript com tipos desta forma. Embora seja um pouco mais detalhado do que usar TypeScript, você se acostuma rapidamente. Também é muito poderoso, contanto que você não esteja escrevendo tipos malucos (o que não deveria acontecer na maioria dos projetos), você ficará bem.

Se você precisar de um tipo complicado (auxiliar), você sempre pode adicionar algum TypeScript em um arquivo .d.ts.

O JSDoc é apenas um trampolim para que pessoas presas a grandes projetos JavaScript possam migrar gradualmente para TypeScript? Eu não acho! A equipe do TypeScript também continua adicionando ótimos recursos ao JSDoc TypeScript, como na próxima versão do TypeScript. O preenchimento automático também funciona muito bem no VS Code.

Importar mapas

Aprendemos como adicionar pacotes externos ao nosso projeto sem uma ferramenta de construção. No entanto, se você dividir seu código em vários módulos, escrever o URL completo repetidamente pode ser um pouco detalhado.

Podemos adicionar um mapa de importação à seção head do nosso index.html:

Agora podemos simplesmente importar este pacote com

import {} from "superstruct"

Como um projeto ‘normal’. Outro benefício é que o preenchimento e o reconhecimento de tipos funcionarão conforme o esperado se você instalar o pacote localmente.

npm install --save-dev superstruct

Observe que a versão em seu diretório node_modules não será usada. Você pode removê-lo e seu projeto continuará em execução.

Um truque que gosto de usar é adicionar:

      "cdn/": "https://esm.sh/",

Para meu mapa de importação. Então qualquer projeto disponível através de esm.sh pode ser usado simplesmente importando-o. Por exemplo.:

import Peer from "cdn/peerjs";

Se você deseja extrair tipos de node_modules para desenvolvimento para este tipo de importação também, você precisa adicionar o seguinte ao compilerOptions do seu jsconfig.json:

    "paths": {
      "cdn/*": ["./node_modules/*", "./node_modules/@types/*"]
    },

Implantação

Para implantar seu projeto, copie todos os arquivos para um host de arquivo estático e pronto! Se você já trabalhou em um projeto JavaScript legado, conhece a dificuldade de atualizar ferramentas de construção que não têm nem 1 a 2 anos. Você não sofrerá o mesmo destino com a configuração deste projeto.

Teste

Se o seu JavaScript não depende das APIs do navegador, você pode simplesmente usar o executor de testes que vem junto com o Node.js. Mas por que não escrever seu próprio executor de testes que roda diretamente no navegador?

/** @type {[string, () => Promise | void][]} */
const tests = [];

/**
 *
 * @param {string} description
 * @param {() => Promise | void} testFunc
 */
export async function test(description, testFunc) {
  tests.push([description, testFunc]);
}

export async function runAllTests() {
  const main = document.querySelector("main");
  if (!(main instanceof HTMLElement)) throw new Error();
  main.innerHTML = "";

  for (const [description, testFunc] of tests) {
    const newSpan = document.createElement("p");

    try {
      await testFunc();
      newSpan.textContent = `✅ ${description}`;
    } catch (err) {
      const errorMessage =
        err instanceof Error && err.message ? ` - ${err.message}` : "";
      newSpan.textContent = `❌ ${description}${errorMessage}`;
    }
    main.appendChild(newSpan);
  }
}

/**
 * @param {any} val
 */
export function assert(val, message = "") {
  if (!val) throw new Error(message);
}

Agora crie um arquivo example.test.js.

import { test, assert } from "@/test.js";

test("1 1", () => {
  assert(1   1 === 2);
});

E um arquivo onde você importa todos os seus testes:

import "./example.test.js";

console.log("This should only show up when running tests");

Execute isto no carregamento da página:

await import("@/test/index.js"); // file that imports all tests
(await import("@/test.js")).runAllTests();

E você tem uma configuração TDD perfeita. Para executar apenas uma seção dos testes, você pode comentar algumas importações de .test.js, mas a velocidade de execução do teste só deve começar a se tornar um problema quando você acumular muitos testes.

Benefícios

Por que você faria isso? Bem, usar menos camadas de abstração torna seu projeto mais fácil de depurar. Existe também o credo de “usar a plataforma”. As habilidades que você aprender serão melhor transferidas para outros projetos. Outra vantagem é que quando você retornar a um projeto construído como este em 10 anos, ele ainda funcionará e você não precisará fazer arqueologia para tentar reviver uma ferramenta de construção que está extinta há 8 anos. Uma experiência com a qual muitos desenvolvedores web que trabalharam em projetos legados estarão familiarizados.

Veja plainvanillaweb.com para mais algumas ideias.