Quando ‘Env’ não é apenas variáveis ​​de ambiente: minha jornada pelo módulo de JavaScript abreviou a toca do coelho

Ou: como passei 3 horas depurando uma única palavra em minha configuração My Docusaurus Confusion Story Picture isto: Estou atualizando o site de documentação para Tolgee (uma plataforma de localização em que trabalho), seguindo o guia de migração do docusaurus, e vejo esta linha: Preseft: [[‘classic’, { /* options */ }]]Entre no modo de tela cheia de saída de tela cheia, me olhando para o ‘clássico’ como ele me ofendeu pessoalmente “o que diabos é ‘clássico’?” Eu pensei. “Isso é uma coisa de javascript embutida que perdi? Uma variável global? Magic?” Passei a hora seguinte: 🔍 Pesquisando meus node_modules por qualquer coisa chamada “clássico” 📖 lendo docussaurus docs tentando descobrir onde isso vem de 🤔 questionar minha compreensão das importações de javascript-ficando cada vez mais frustrado, então descobri a verdade: “clássico” é na verdade @docusaurus/clássico predefinido em disfarce. Mente = soprado. Mas aqui está o kicker – essa “mágica” não é exclusiva do docusaurus. Está em toda parte no ecossistema JavaScript. O que são as taquigrafias do módulo? As abreviação de módulos são um recurso de conveniência que permite usar nomes abreviados em vez de nomes de pacotes completos nos arquivos de configuração. Quando uma ferramenta encontra uma abreviação, ela a resolve automaticamente no nome completo do pacote usando regras predefinidas. O padrão A maioria das ferramentas JavaScript segue uma estratégia de resolução semelhante: tente o nome exato primeiro: clássico Pacote Official Scoped Official: @ToolName/Type Classic Try Community Convention: ToolName-Nome-Type-Classic A primeira partida vence. A torção da trama: está em toda parte! Depois que entendi o que estava acontecendo com o Docusaurus, comecei a ver esse padrão em todos os lugares. Deixe -me explodir com alguns exemplos: Babel – o mestre de abreviação de OG lembra -se daquele inocente “Env” em sua configuração de Babel? Sim, não é isso que você acha que é. // Babel.config.js {“Presets”: [
“env”, // → @babel/preset-env (SURPRISE!)
“react”, // → @babel/preset-react
“typescript” // → @babel/preset-typescript
]”plugins”: [
“transform-runtime”, // → @babel/plugin-transform-runtime
“proposal-decorators” // → @babel/plugin-proposal-decorators
]
} Digite o modo de tela cheia de saída do modo de tela cheia Drake Pointing: Writing@Babel/Predefinição Aprovando: Escrever “Env” Babel possui o sistema de normalização de nomes mais sofisticado com regras detalhadas: Pacotes não escondidos: “Mod”/Mod “@” Babel-Plugin-Mod “Scoped Packages:” Babel/Mod/Mod “→ → → “@Scope/Babel-Plugin-Mod” Eslint-o “óbvio” (uma vez que você souber), o Eslint realmente tem a convenção de nomenclatura mais clara, mas ainda anda as pessoas: // .eslinTrc.js {“Extende”: [
“airbnb”, // → eslint-config-airbnb
“prettier”, // → eslint-config-prettier
“react-app” // → eslint-config-react-app
]”plugins”: [
“react”, // → eslint-plugin-react
“import”, // → eslint-plugin-import
“jsx-a11y” // → eslint-plugin-jsx-a11y
]
} Digite Modo de tela completa Sair Modo de tela cheia Eu percebendo que todas as configurações que já escrevi estão cheias de regras de configuração de plug-in de Eslint Hidden Eslint são realmente previsíveis: configurações: “Nome” → “Eslint-Config-name” Plugins: “Nome” → “Eslint-Plugin-Name” Scoped: “Scope/Nome/Nome” ” Nightmare agora que conheço o padrão, vamos revisitar minha confusão original: // docusaurus.config.js – a cena do crime {Presets: [
[‘classic’, { // → @docusaurus/preset-classic (THE REVEAL!)
docs: { /* */ },
blog: { /* */ }
}]
]plugins: [
‘sitemap’, // → @docusaurus/plugin-sitemap
‘content-pages’ // → @docusaurus/plugin-content-pages
]
} Digite o modo de tela cheia de tela cheia de tela cheia 1: “Classic” é MagicBrain 2: “Classic” é um abreviação 3: Todas as ferramentas JS usam abreviação de abreviação 4: Eu tenho usado abreviação em todos os lugares sem saber que o docusaurus tem documentação abrangente sobre isso, mas encontrando quando você está confuso? Boa sorte! Postcss – resolução simples // postcss.config.js {plugins: [
“autoprefixer”, // → autoprefixer (exact match)
“cssnano”, // → cssnano (exact match)
“tailwindcss” // → tailwindcss (exact match)
]
} Digite o modo de tela fullcreen Sair do modo de tela cheia Roll – Pacotes Scoped // rollup.config.js {plugins: [
“resolve”, // → @rollup/plugin-node-resolve
“commonjs”, // → @rollup/plugin-commonjs
“typescript” // → @rollup/plugin-typescript
]
} Digite o modo de tela cheia de tela cheia de tela cheia Vite – Seguindo o padrão // vite.config.js {plugins: [
“react”, // → @vitejs/plugin-react
“legacy” // → @vitejs/plugin-legacy
]
} Digite o modo de saída de tela cheia de tela cheia Por que esse padrão existe? Após minha sessão de depuração de 3 horas, tive que perguntar: por que as ferramentas de JavaScript fazem isso conosco? Convenção sobre a configuração (a filosofia) Se uma abreviação resolver em um arquivo de configuração e nenhum desenvolvedor o entende, isso emitirá um som? The JavaScript ecosystem LOVES “convention over configuration”: Less typing: ‘env’ vs ‘@babel/preset-env’ (saved 15 characters!) Cleaner configs: Your babel.config.js doesn’t look like XML Predictable patterns: Once you know the rules, you can guess package names Flexibility: Both ‘env’ and ‘@babel/preset-env’ work The Ecosystem Benefits (When It Works) Consistency: Aprenda uma vez, reconheça em todos os lugares a descoberta: “Aposto que há uma eSlint-Plugin-REACT” Manutenção: as configurações mais curtas são mais fáceis de digitalizar a felicidade do desenvolvedor: menos Boilerplate = mais tempo para a codificação real do lado sombrio: por que está absolutamente confundindo magia oculta em todos os lugares // o que você vê predeftes: [[‘classic’]]// O que realmente acontece (nos bastidores) Predefinições: [[‘@docusaurus/preset-classic’]]Digite o modo de tela cheia Sair da tela cheia Modo Dica do iceberg: Seu Configunderwater: toda a resolução do módulo que está acontecendo literalmente não há indicação visual de que ‘clássico’ se torne algo completamente diferente. Documentation Roulette The docs are inconsistent: Tutorial shows: ‘classic’ API docs show: ‘@docusaurus/preset-classic’ Stack Overflow shows: Both, with no explanation Your brain: 🤯 Debugging Hell When things break, you get errors like: Cannot resolve module ‘classic’ Enter fullscreen mode Exit fullscreen mode Me trying to figure out which of the 3 resolution attempts failed The error doesn’t tell you: Which resolution step failed What was actually attempted Whether the package is missing or the name is wrong Every Tool Is Special Each tool has its own special snowflake implementation: Babel: Most complex rules ESLint: Clear patterns but different prefixes Docusaurus: Scoped packages only PostCSS: Mostly exact matches Rollup: Different scope handling Implementation Deep Dive How Resolution Actually Works Most tools implement something like this: function resolveModule(name, moduleType) { const attempts = [
name, // exact
`@${toolName}/${moduleType}-${name}`, // official
`${toolName}-${moduleType}-${name}` // community
]; para (const tentativa de tentativas) {tente {return requer.resolve (tentativa); } catch (e) {continue; }} lança um novo erro (`não pode resolver $ {name}`); } Digite Modo de tela FullScreen Sair FullScreen Modo Pacote Scoped Manuseio para pacotes com escopo como @my-company/Awesome: function resolvescopedModule (nome, moduletype) {const [scope, packageName] = name.split (‘/’); se (! } // @scope/nome → tente ambos os formulários const tentativas = [
name, // @scope/name
`${scope}/${toolName}-${moduleType}-${packageName}` // @scope/docusaurus-plugin-name
]; // … Lógica de resolução} Digite o modo de tela cheia de tela cheia de tela cheia como sobreviver ao apocalipse abreviado para autores de ferramentas (por favor, escute!) Drake rejeitando: mostrando apenas abrevias em exemplos de aprovação: Mostrando clássicos e clássicos e mais clássicos: Mossos clássicos: “Classic” e ” @docusurus/pretet-classic em exemplos de clássicos” @docusaurus/preset-classic, docusaurus-preset-classic” Cross-reference docs: Link to your shorthand explanation from EVERY config example Consistent patterns: Don’t reinvent the wheel – follow Babel/ESLint conventions For Developers (My Hard-Learned Lessons) Me after learning about shorthands: Everything is fine When confused, use full names: @docusaurus/preset-classic never lies Check your package.json: See what’s actually installed vs what you’re referencing Use IDE superpowers: Many editors show resolved names on hover Debug systematically: Replace shorthands with full names when things break Learn the patterns: Once you know Babel’s rules, you can guess others Debugging Shorthand Issues Common Problems Package not installed: Shorthand resolves but package missing Wrong resolution: Resolves to unexpected package Typos: Small mistakes in shorthand names Version conflicts: Múltiplos pacotes correspondem a etapas de depuração de padrões Experimente o nome completo: Substitua a abreviação com o nome completo do pacote Verifique a instalação: Existe o pacote de verificação em node_modules Verifique a resolução: use o modo de depuração da ferramenta se disponível Verificar Nomeação: Verifique os nomes oficiais de pacotes Ferramentas de depuração # Verifique o que está instalado npm list | Grep predefinido # Tente resolver o nó manualmente -e “console.log (requer.Resolve (‘@docusaurus/predefinição clássica’))” # Enable Modo de depuração (específico da ferramenta) Debug = Docusaurus* NPM Start Start Start Modo de tela Full Screen Erldring Mementos de tela futura mais ferramentas Adotação de ferramentas: Ferramenta para a ferramenta Spreseling para spreading para spread para que a ferramenta seja mais importante para a fullcreen Modersing Mestering Trends Trends Approtent: Ferramenta para a ferramenta de ferramentas para a ferramenta para que a ferramenta seja mais importante para a fullcreen. O preenchimento automático e a resolução sugere a padronização: algum movimento em direção a padrões comuns Recomendações para o ecossistema melhorar: melhor documentação: sempre mostre as duas formas ferramentas aprimoradas: melhor suporte ao IDE para padrões de mensagens de erro de resolução: Mostrar resolução de tentativas de educação comunitária: mais artigos como este! The Final Revelation Small brain: Getting confused by ‘classic’Medium brain: Understanding it’s a shorthandLarge brain: Recognizing the pattern everywhereGalaxy brain: Writing an article to help other confused developers After my 3-hour journey down the shorthand rabbit hole, I’ve learned that: It’s not magic: Just very well-hidden conventions It’s everywhere: Once you see it, you can’t unsee it It’s actually helpful: When you understand the rules It’s poorly Documentado: A conexão entre exemplos e explicações geralmente está faltando o que isso significa para você da próxima vez que você vê ‘Env’, ‘Classic’, ‘Airbnb’ ou qualquer outra corda misteriosa em uma configuração de JavaScript: não entre em pânico: é provavelmente o que se segue a mais que seja o que é o que é o que é o que é o que é o que é o que é o que é o que é o que é o que é o que é o que é o que é o que é o que é o que é o que é o que é o que é o que você está fazendo com exceão em geral, com o objetivo de avaliar que é que é que é que é um que é um que é um dos melhores e os que estão sendo feitos e os que estão sendo feitos. Suas convenções, mas às vezes esquece de explicá -las aos recém -chegados. Agora você está em segredo! Você ficou confuso com as taquigrafias do módulo JavaScript? Compartilhe suas histórias de guerra nos comentários – vamos tornar o ecossistema mais acolhedor para todos! 🚀 Sobre o autor: Trabalho em Tolgee, uma plataforma de localização de código aberto que simplifica o i18n para desenvolvedores. Se você está construindo aplicativos multilíngues e cansado de fluxos de trabalho de tradução complexos, confira! Referências

Fonte