Try   HackMD

Why are deep imports bad?

Many apps use deeply nested file path package imports across their packages:

import { canary } from 'owa-service/lib/foo/bar/canary';

This as a bad practice - pulling arbitrary source files from the lib folder means that:

  1. The package must be built first for compilation to work, or the path must be programatically remapable.
  2. The consumed package api surface becomes larger than may have been anticipated by the author. The fact that you CAN import any arbitrary source file means that every file becomes a contract; you can not rename, move, or change the exports of that file without potentially breaking something which depends on that. Even changing the case of a filename will break the contract.
  3. The lib folder name itself is an abstraction leak as it implicitly refers to a module format. Its contents have been a subject of debate in the past; does it contain commonjs code? es modules? or {some future format}? When a developer wants to import a subtree of a package, it should be as simple as possible; e.g. import Button from "package/Button" rather than from "package/lib/components/Button/index". And, intellisense should be available to help the dev know what's allowed to be imported.

Node package.json format has recently addressed these scenarios with the added exports property. This property allows libraries to be explicit about what entry points are allowed, which can help with intellisense and with keeping the api surface explicit and minimal:

{
  exports: {
    ".": "./lib/index.js",
    "./Button": "./lib/components/Button/index.js"    
  }
}

To support multiple module formats, we use standard "conditions" which will be used to resolve paths. When a path is being resolved using require, the require condition will be used. And when being imported, import will be used. Now we can support both esm and cjs without the path referring to the module flavor:

{
  exports: {
    ".": {
      "require": "./lib-commonjs/index.js",
      "import": "./lib-esm/index.js",      
    },
    "./Button": {
      "require": "./lib-commonjs/components/Button/index.js",
      "import": "./lib-esm/components/Button/index.js"
    
  }
}

So many benefits to this:

  1. No leaky abstractions
  2. Smaller import paths (/Button rather than lib/components/Button.)
  3. Works with cjs or esm without special remapping
  4. Contracts are explicit, meaning you can't import lib/top/secret/internals without them being added to the map.

We can take this a step further by providing a source condition for development mode, which helps to translate the above mappings into source files (tsx/ts), future reducing complexity in resolving modules in a dev environment:

{
  exports: {
    ".": {
      "source": "./src/index.tsx",
      "default": "./lib/index.js"
    }
  }
}

The source condition can be added to conditionNames in webpack config to auto resolve source files.

References

Exports details in package.json config:
https://nodejs.org/api/packages.html#packages_subpath_exports

Webpack config details on adding resolve conditions:
https://webpack.js.org/configuration/resolve/#resolveconditionnames

Last changed by 
 
David Zearing
1
1543

Read more

Why are const enums bad?

I always forget why, so time to write it down! They interfere with isolatedModules support and transpilers. Imagine that a transplier will convert your TypeScript code into Javascript, without parsing the typings of the dependencies. That means if you import { SomeConstEnum } from 'dependency' in your code, it doesn't know it's a const enum, or an interface, or a js object, and as such the transpiler leaves the import there. The problem with this is that now, if you parse the javascript you just emitted, the named import will fail. In the raw JavaScript ES module produced, you expected TS concepts like type and interface, and of course const enum to be dropped, and all your SomeConstEnum.foo references to be replaced with literals, but that can't happen without knowing what the thing was in the first place. The point of isolated transpilation is quick development. You can have thousands of packages in your repo. If you don't need to parse dependency types, you can transpile massive quantities of code, all in parallel, in milliseconds rather than minutes. But they've never caused me problems before! Here are the rules - you can use them in your project; just don't export them. You might have been following the rules all along.

Feb 1, 2023
Addressing the shortcomings of peer dependencies

Peer dependencies are intended to help reduce duplicate installs in applications by allowing libraries to opt out of introducing them, yet fall short to give control to app hosts on what they expect to be singletons. They also give no way for producers to indicate common intent. They put singleton package expectations in the wrong hands (middle-tier libraries rather than app hosts and atomic libraries) They are easy to misunderstand due to poor vocabulary (peer does not imply singleton) They are difficult to resolve (so many unmet peer dependency warnings ignored...) They add unnecessary burden on app consumers (e.g. installing emotion dependencies with mui) Error messages don't make it easy to resolve them. The roles - who is involved? For this article we're going to refer to the following roles:

Jul 27, 2022
Read more from David Zearing
Published on HackMD