DEV Community: nyxb

🧙‍♂️ The Enchanted Tale of JavaScript's Magical Evolution - ESM & CJS 🌟

nyxb — Mon, 15 May 2023 09:46:18 +0000

🏰 Prologue - The Kingdoms of ESM & CJS

Once upon a time, in the vast universe of JavaScript, there existed two magical realms - ESM, the kingdom of ECMAScript modules, and CJS, the land of CommonJS. Over the past decade, due to the absence of a unified magical script (module system) of JavaScript, CJS (signified by the incantation require('xxx') and module.exports syntax) was the universal spell used in Node.js and NPM packages.

However, in the fateful year of 2015, ESM's powerful runes finally emerged as the standard incantation, prompting a gradual migration towards native ESM. This enabled named exports, better static analysis, tree-shaking, and native browser support. 🌳📚

// CJS
const circle = require('./circle.js')
console.log(`The area of a circle of radius 4 is ${circle.area(4)}`)
// ESM
import { area } from './circle.mjs'
console.log(`The area of a circle of radius 4 is ${area(4)}`)

ESM was like the prophecy of a new dawn, offering a promising future for JavaScript. Node.js v12 introduced experimental support for native ESM, which was later stabilized in v12.22.0 and v14.17.0. As we approached the end of 2021, many packages began to be shipped in pure-ESM format or as a hybrid of CJS and ESM; meta-frameworks like Nuxt 3 and SvelteKit recommended users to adopt an ESM-first environment. 🚀

However, this migration was akin to a grand quest, full of challenges and adventures. For most library authors, shipping dual formats became a safer, smoother path, enabling them to reap the benefits of both realms.

🐉 The Challenge of Compatibility

Despite ESM's promising future, the road was fraught with obstacles. One such hurdle was the inability to use ESM packages in CJS. Node.js was smart enough to allow CJS and ESM packages to co-exist, but attempting to use ESM packages in CJS would result in an error. 🚧

// in CJS
const pkg = require('esm-only-package') // will throw an error

The underlying issue was that ESM is asynchronous by nature, which means it couldn't be imported into the synchronous context of require. This generally meant that to use ESM packages, you also needed to use ESM. There was one exception though - ESM packages could be used in CJS using dynamic import().

// in CJS
const { default: pkg } = await import('esm-only-package')

Meanwhile, if you were able to use ESM directly, it was significantly easier as import supports both ESM and CJS.

// in ESM
import { named } from 'esm-package'
import cjs from 'cjs-package'

Some packages started shipping pure-ESM packages, advocating for the ecosystem to transition from CJS to ESM. While this might be the "right thing to do", considering the majority of the ecosystem was still on CJS and the migration wasn't a walk in the park, I found myself more inclined to ship both CJS and ESM formats for a smoother transition.

🧪 The Alchemical Recipe - package.json

Fortunately, Node allowed us to hold these two realms in balance, marking the scripts with "type": "module" in package.json. This made .js files to be interpreted as ESM by default. However, if we wanted to use both ESM and CJS in the same codebase, we needed to use .cjs and .mjs extensions for CJS and ESM respectively. This was akin to placing a magical seal to ensure harmony.

// package.json
{
  "type": "module",
  "main": "./index.cjs",
  "module": "./index.mjs",
  "exports": {
    "import": "./index.mjs",
    "require": "./index.cjs"
  }
}

In the above example, "main" and "module" entries pointed to our CJS and ESM entries respectively. The "exports" field was especially powerful. It allowed us to map different entry points for require and import, thus ensuring compatibility with both.

// index.mjs
import { named } from 'esm-package'
import cjs from 'cjs-package'
export default named + cjs

// index.cjs
const { named } = require('esm-package')
const cjs = require('cjs-package')
module.exports = named + cjs

While this was a good start, it wasn't perfect. To fully support both ESM and CJS, you needed to ensure that your code and its dependencies were compatible with both module systems. This could be a significant challenge, but with careful planning and a thorough understanding of both systems, it was achievable.

🧭 The Journey Ahead

The migration from CJS to ESM may seem like a long and winding journey, but it's a path that the JavaScript community is steadily traversing. With every challenge, there are new learnings, and with every step forward, we're making the ecosystem more future-ready.

As with any quest, patience and persistence are the keys to success. The future of JavaScript is bright with ESM, and the potential it holds is truly magical. So, let's brace ourselves for the exciting journey ahead and be a part of this evolution. 🌈💡

// The future is here, and it's written in ESM!
import { future } from 'javascript'
console.log(`Welcome to the ${future} of JavaScript!`)

🌟 Epilogue

This tale is an ongoing saga in the world of JavaScript. It serves as a testament to the dynamism of this language and the relentless pursuit of its community for better, more efficient coding practices.

Remember, whether you're an ESM enthusiast or a CJS loyalist, in the end, we're all JavaScript wizards weaving our own magic. Let's continue to evolve, innovate, and inspire each other in this enchanted tale of JavaScript's magical evolution. 🧙‍♂️🌟🚀

🗣 The Oracles Speak - The Tools of Prophecy

In the quest of magical JavaScript transformation, there are two legendary tools that JavaScript wizards have been using – tsup and buildkarium. These tools help in creating a balance between the ESM and CJS realms, ensuring a smoother transition.

⚡ `tsup`

The first magical tool, tsup by @egoist, offers a zero-config building experience for TypeScript projects, bringing harmony between CJS and ESM.

$ tsup src/index.ts --format cjs,esm

The command above will create two files: dist/index.js (for CJS) and dist/index.mjs (for ESM), thus preserving the balance between the two realms.

🏗 `buildkarium`

The second tool in our arsenal, buildkarium by the @nyxblabs organization, is a more generalized, customizable, and powerful tool. It offers a unique feature called Stubbing, which eliminates the need for a watcher process. It's akin to a magical charm that ensures your code is always up-to-date.

$ buildkarium --stub

Running the command above once is all you need to keep your library code up-to-date!

The buildkarium tool also enables Bundleless Build, which allows you to maintain the structure of your source code, enabling on-demand importing of submodules, thus optimizing performance.

// karium.config.ts
import { defineBuildConfig } from 'buildkarium'

export default defineBuildConfig({
  entries: [
    // bundling
    'src/index',
    // bundleless, or just copy assets
    { input: 'src/components/', outDir: 'dist/components' },
  ],
  declaration: true,
})

🌉 Bridging Context Misalignment

Despite these powerful tools, wizards must remain cautious of context misalignment between ESM and CJS. ESM does not recognize __dirname, __filename, require, require.resolve, instead it uses import.meta.url. However, with a little extra spellcasting, we can conjure up a solution:

import { dirname } from 'path'
import { fileURLToPath } from 'url'

const _dirname = typeof __dirname !== 'undefined'
  ? __dirname
  : dirname(fileURLToPath(import.meta.url))

The code snippet above provides an isomorphic __dirname, working in both ESM and CJS contexts.

🌟 The Magical Epilogue

This tale of ESM and CJS is far from over, the JavaScript community continues its quest for the most efficient coding practices. As we venture forth, let's embrace the magical evolution of JavaScript, making the most of both the CJS past and the ESM future.

Remember, whether you're working in ESM or CJS, we're all JavaScript wizards, conjuring up our own magical code in this ever-evolving landscape. 🧙‍♀️🌟🚀

2023-PRESENT © Dennis Ollhoff

🧙‍♂️✨ Welcome to the magical world of indentation! 🌟📜

nyxb — Thu, 04 May 2023 15:36:01 +0000

🔮 Ever found yourself in a mystic quest to decide if 2 or 4 spaces is best for your new code adventure? You've come to the right place!

I could cast a spell 🪄 and tell you which of the two is the ultimate choice. But as you probably know, it's a matter of individual preference for personal/solo quests, and coding guidelines if you're embarking on an epic journey with an organization (assuming they have coding guidelines).

As a code wizard 🧙‍♂️, my choice is to wield 2-space indentation for front-end spells and 4-space indentation for backend enchantments. However, 4-space indentation can sometimes create more margin than needed. On the other hand, 2-space indentation may not provide enough space, reducing the readability of your magical incantations.

Why not harness the power of both realms? Embrace 3 spaces/tab! ⚡️ It's a no-brainer, right? The 2 and 4 space conventions have been widely adopted across the enchanted coding kingdoms. Don't waste time debating whether 3-space indentation is valid for coding. I've been using 3 spaces in my new projects, and I make sure to share this secret with my fellow adventurers at the start of each new quest.

For those interested, you can find my ESLint configuration and read about the epic battle between Prettier and ESLint in this thrilling tale: Prettier - A Double-Edged Sword for Code Formatting 🗡️

That said, I'll save the space vs tab indentation comparison for another thrilling tale.

I'd be delighted to hear your thoughts on 3 space/tab indentation in the comments section below! 📣 Thanks for joining me on this fantastic journey! 🌈

Prettier: A Double-Edged Sword for Code Formatting 🎭

nyxb — Tue, 18 Apr 2023 13:40:26 +0000

Why I Admire Prettier
The Peculiar Situation
The Rigidity of Prettier
The Line Wrap Dilemma
The Prettier and ESLint Saga
An Alternative Approach
Final Thoughts

My Persistent Effort to Articulate My Sentiments 😣

Despite numerous attempts to pen down this post, I've struggled to express my feelings about Prettier. This time around, I'm committed to clarifying my position for future reference.

Disclaimer: I don't oppose Prettier—in fact, I appreciate it.

Why I Admire Prettier ❤️

Prettier is an invaluable tool that has spared me a tremendous amount of time. I'm grateful to the maintainers and contributors who have put in the effort to establish a reliable foundation for neat, consistent code across the developer community. Although the title may seem provocative, I do frequently use Prettier for interactive documentation and playgrounds with technologies like TypeScript and Next.js. Its seamless support for a wide range of languages allows me to effortlessly enhance the appearance of generated code.

The Peculiar Situation ❓

Upon exploring my open-source projects, you might observe that I rarely rely on Prettier for formatting source code. In this post, I intend to elaborate on the reasoning behind this decision:

The Rigidity of Prettier 🧱

Prettier markets itself as "an opinionated code formatter."

Being opinionated implies that it won't cater to everyone's preferences. Prettier enforces numerous hard-coded decisions to offer a minimal configuration interface. While this approach simplifies usage (which is fantastic!) and promotes consistency across projects, it also restricts your ability to fine-tune the appearance of your code.

Although I appreciate most of Prettier's choices, it can be frustrating to encounter formatting decisions that you dislike and cannot work around.

The Line Wrap Dilemma 📏

One aspect that particularly irks me is the automatic wrapping/unwrapping of code based on line length. Prettier employs a printWidth concept, which limits each line to a specified width (80 characters by default). In general, this approach ensures that code fits within a single screen and eliminates the need for horizontal scrolling.

However, I've often found that it compromises readability and complicates git diffs.

In a recent PR review, highlight an example of this issue:
Formatters truly shine in their brilliance, particularly during PR reviews. However, they can also present challenges, such as when a newly added piece of code initiates a line break. The diff, in this case, fails to reveal the actual changes. It would be splendid if diff viewers were Prettier-conscious and considered line breaks as mere spacing.

Modifying a JavaScript string literal to exceed the printWidth value causes Prettier to wrap the line forcibly. This action disrupts inline diffing and complicates the review process. In another pull request, shortening the string could lead Prettier to unwrap the lines, creating unnecessary noise.

The following image illustrates another example:

While the printWidth of 42 is used for demonstration purposes, this issue persists regardless of the printWidth value.

On the left, we have the input code, and on the right, the output from Prettier. It's apparent which one is "more visually appealing." In my opinion, Prettier's strict adherence to its rule hinders code readability and modification, which contradicts the primary objective of formatting—to enhance code readability.

The real issue lies in the fact that this behavior is non-negotiable. You cannot disable it entirely(#3468). Increasing the printWidth merely postpones the problem and affects other files you haven't touched. The only workaround is to use // prettier-ignore, but the "all or nothing" choice defeats the purpose of utilizing Prettier in the first place.

The Prettier and ESLint Saga 🤹

Prettier, as a code formatter, focuses solely on code styles and not logic. Consequently, many projects use ESLint in conjunction with Prettier to check logic as well. If you've ever configured this setup, you might have noticed some overlapping functionality between the two—ESLint can also lint code styles. A common practice is to use eslint-config-prettier to disable overlapping rules in ESLint (other solutions are also available).

However, this approach creates a messy situation for me:

ESLint's auto-fix feature can format code just as effectively as Prettier, but with greater flexibility.

An Alternative Approach 🔄

ESLint is essential to my workflow for ensuring code quality. Since ESLint is already capable of formatting, I prefer to utilize it exclusively.

I dedicated some time to configuring my ESLint and created a config preset:

@nyxb/eslint-config
As a result, the setup configuration can be minimal:

npm i -D @nyxb/eslint-config

// .eslintrc
{
  "extends": "@nyxb"
}

That's all it takes. With IDE extensions, auto-fixing on save is also possible. It functions similarly to Prettier but respects your choices regarding line breaks and adheres to numerous linting best practices. Naturally, it's opinionated to cater to my needs. However, it could serve as a helpful reference for creating your own version.

Final Thoughts 🌅

This post aims to share my personal experiences and opinions. Of course, you may have differing viewpoints and need not agree with me. I'm not criticizing Prettier for its design. Different tools have different purposes and focuses, so there's no definitive "better" or "worse." It's about choosing the right tools for the right situations. I'll continue to be a satisfied Prettier user for cases where I don't require maximum customizability, while exclusively using ESLint for my projects' source code.

I hope this provides clarity and offers some insights. Cheers!

@nyxb/eslint-config repo

cd ..
CC BY-NC-SA 4.0 2023-PRESENT © Dennis Ollhoff

🎩✨ Reproductions: The Magic Behind the Scenes

nyxb — Tue, 11 Apr 2023 21:14:43 +0000

Join me on this enchanting journey as we unravel the mystical world of reproductions.

🚀🔮 A Thrilling Odyssey into the Realm of Open Source Enchantments: Embrace the "As-Is" Adventure

Imagine this: you're a brave wizard venturing into the infinite cosmos of Open Source Software (OSS). You encounter the legendary MIT License, a magical parchment known far and wide in this land, whispering a cryptic prophecy:

The software is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement.

The "as is" proclamation signifies you've been bestowed the power to utilize the spell (code), modify it, or even transfigure it to your will, all in its current form. However, the spell creators stand liberated from any obligation to mend or amplify anything you might face now or later. They gain no advantage from your use, and there's no vow of ceaseless support. In this OSS expedition, you are the master of your own magic.

Sounds daunting, right? But fear not, for the reality is more merciful. In the expansive universe of open source projects, a trust pact binds users and maintainers. Users act as scouts, reporting obstacles they encounter or sharing their magical solutions through dynamic discussions and pull requests. Meanwhile, maintainers serve as the project's backbone, reviewing and making decisions, orchestrating new versions, and managing distributions. This harmonious alliance of users and maintainers works tirelessly, bound by a common goal: to enhance the software for the greater good.

💖 The Art of Maintenance: A Labour of Love

The life of software is an eternal dance, never truly reaching completion. Maintenance is the life-force of a project, ensuring its pulse remains steady with timely bug fixes and security updates. It is the key to sustaining the project in the long run. However, tasks such as triaging issues, reviewing PRs, and engaging in discussions demand immense effort from maintainers.

In the open source kingdom, the user-to-maintainer ratio often tips perilously out of balance. Many popular projects have only one or two unsung heroes working tirelessly behind the scenes. As a project grows and attracts a larger user base, the maintenance tasks required may quickly surpass the capacity of these devoted individuals.

🗺️ The Quest for Reproduction: Unearthing the Root of the Issue

💥 The Power of Reproduction

Crafting a flawless minimal reproduction of a potential issue can be a powerful charm for maintainers, allowing them to pinpoint the root cause and swiftly implement a fix. Without such a reproduction, maintainers are left to decipher the issue from mere descriptions or screenshots, unsure whether the problem stems from the project itself or external factors. To unravel this mystery, maintainers may need to embark on a time-consuming journey, attempting to reproduce the issue themselves or delving into the labyrinthine projects shared as "non-minimal reproductions". Hours may be lost, only to discover an issue that is either nonexistent or impossible to reproduce. What if there are hundreds of such issues to tackle?

In my view, requesting a minimal reproduction seeks to balance the efforts expended. If every adventurer took the time to create a minimal reproduction before presenting their issues, it would save maintainers countless hours (and perhaps even help users uncover solutions or mistakes on their own, negating the need for an issue). A thoroughly investigated and well-articulated issue may also inspire maintainers to devote their time and energy in return.

🎨 The Art of Crafting a Minimal Reproduction

This section is adapted from "Please include a repro" by Rich Harris. For a more detailed explanation, watch Rich Harris' spellbinding presentation.

At times, there may be a project-specific method to demonstrate problems – for example, Rollup, Svelte, and Vue all have dedicated magical platforms, known as REPLs. Embrace them!

However, sometimes it's not feasible to illustrate the problem with a REPL. In these cases, follow these magical steps:

🏰 Forge a sample repo on GitHub, Stackblitz, or another platform of your choosing.
🎭 Exhibit the problem – and only the problem. Pare it down to the absolute minimum of code that reliably demonstrates the issue. Eliminate any dependencies unrelated to the problem.
📜 Embed all dependencies in package.json. If the maintainer can't clone the repo and execute npm install && npm run build (or similar – see point 4) to witness the problem because they require some globally installed CLI tool or otherwise, it becomes more challenging to solve the issue.
🖋️ Incorporate instructions and a description of the expected and actual behavior in the repo, ideally in README.md. This document should also include a link back to the issue. If there are any instructions beyond npm install && npm run build, list them here.

🌅 The Journey's End

As a maintainer, I am grateful for every issue and pull request submitted. I acknowledge that some closed issues lacking reproductions may still harbor genuine bugs requiring attention. However, to avoid being overwhelmed by a flurry of notifications, maintainers must prioritize their tasks. Keeping the number of issues manageable is one way to ensure a project's long-term health.

I believe open source is about conjuring spectacular creations together, not placing the entire burden on maintainers' shoulders. Together, we can forge a more vibrant and magical community. Thank you for joining me on this enchanting journey. 🙏✨🎩