TRI

VIKRAM

.

You cannot make everyone happy.

But you can try your best.

#javascript #nodejs #npm

Note: Suggestions are based on assumption that you maintain a package on npm using package.json

It depends!

on what/how of the problem solved by your package

and where/how do users want to use it.

Ask them!

and if your package is popular, they WILL tell you.

You can also populate data in telemetry, if supported.

WHY, HOW and WHAT of

Browser, Server, Native,

Module formats, Sizes,

Types, Debugging, Tracing

JavaScript is THE language used for scripting

in the browsers.

[1]: https://webassembly.org/

[2]: https://github.com/appcypher/awesome-wasm-langs

WebAssembly allows non-JS code to run on browsers

But it's likely to be used for specific use cases - like compute-intensive apps

[1]: https://docs.npmjs.com/cli/v8/configuring-npm/package-json#browser

Use browser field in package.json

"browser": "./browser/main.js",

"browser": {
  "module-a": false,
  "module-b": "./shims/module-b.js",
  "./server.js": "./shims/client.js",
}

🪦 Internet Explorer has "retired" on June 15, 2022!

[2]: https://www.theregister.com/2022/04/26/apple_ios_browser/

[3]: https://jobs.apple.com/en-us/search?search=WebKit

[1]: https://www.microsoft.com/en-us/download/internet-explorer.aspx

💪 Safari likely getting competitive!

Isn't JavaScript support fragmented on browsers?

Yes. But...

📈 Deno is being used in more products.

[3]: https://blog.cloudflare.com/workers-open-source-announcement/

☁️ Cloudflare Workers is going Open Source.

🏆 Node.js is among the popular server runtimes.

[1]: https://www.google.com/search?q=most+popular+server+runtime 

[2]: https://deno.land/showcase

🥟 Bun is going viral by prioritizing performance.

[4]: https://bun.sh/

😎 Web-interoperable Runtimes Community Group

is collaborating on API interoperability of web platform APIs across runtimes.

[1]: https://wintercg.org/

Fragmentation existed for years on the browser.

Is it bad that now there are competing server runtimes?

NO.

Just add filepath in main entry of package.json

"main": "./dist/main.js",

[1]: https://docs.npmjs.com/cli/v7/configuring-npm/package-json#main

↔️ If most of your users are on Deno, you can publish your Deno module on npm using dnt.

🤝 Deno v1.25 added experimental npm support.

[1]: https://deno.com/blog/v1.25#experimental-npm-support

[2]: https://deno.land/manual/node/dnt

👍 Any Node.js package that uses webpack or another polyfill bundler runs in Cloudflare Workers.

[1]: https://blog.cloudflare.com/node-js-support-cloudflare-workers/

❓Bun natively implements many Node.js and Web APIs.

[1]: https://bun.sh/#explain

As of August 2022, Bun is pre-alpha. The parent company is aiming stable release by Feb 2023, so look out for updates.

It depends!

Support the server runtimes your users want.

[1]: https://web.dev/learn/pwa/progressive-web-apps/#challenges

[2]: https://javascript.plainenglish.io/1653901ce244

🏎 JavaScript Native performance trade-off have reduced significantly over the years.

⚠️ PWAs have limitations, like lack of push notifications.

You write JavaScript code, but the UI framework creates native apps.

[1]: https://reactnative.dev/docs/platform-specific-code

📱 React Native parses code from .native.(js|ts) extension.

[2]: https://v7.docs.nativescript.org/core-concepts/project-structure-app

[3]: https://docs.flutter.dev/development/platform-integration/platform-channels

📱 NativeScript/Flutter/Ionic frameworks doesn't mention about platform specific JavaScript code.

It depends!

Support the native frameworks your users want.

Modules are building blocks for software.

Module format is syntax used to define a module.

When JavaScript was getting popular in early 2000s, there was no standard module format. Multiple module formats were developed and used in parallel.

Conversations may get heated because of opinions when we talk about module systems.

Take suggestions with a grain of salt.

ESM (ECMAScript): Official standard format.

CJS (CommonJS): Original module format in Node.js

AMD (Asynchronous Module Definition): was specifically made for frontend.

UMD (Universal Module Definition): was specifically made to work universally.

If supporting single module system, add filepath in main entry.

"main": "./dist/main.js",

[1]: https://docs.npmjs.com/cli/v7/configuring-npm/package-json#main

[2]: https://nodejs.org/api/packages.html#conditional-exports

If supporting both CJS/ESM, use conditional exports.

"exports": {
  "import": "./dist/main.js",
  "require": "./dist/main.cjs"
}

[1]: https://nodejs.org/api/packages.html#approach-1-use-an-es-module-wrapper

For supporting CJS/ESM, you can also use ESM module wrapper

// dist/index.cjs
exports.name = 'value';

// dist/index.mjs

import cjsModule from './index.cjs';
export const name = cjsModule.name;

This can be automated using gen-esm-wrapper.

[2]: https://www.npmjs.com/package/gen-esm-wrapper

🔥🔥🔥 Ideally, you should only support ESM. 🔥🔥🔥

But that would break users on Node.js whose application code is in CommonJS format.

Be a good citizen of JavaScript ecosystem, and support both CJS/ESM if you have to support Node.js

Publish size: Size of the package being published.

Install size: Size of node_modules folder when your package is added as a dependency.

Bundle size: Size of the file generated when a bundler is used on the application code using your package.

If publish/install size is small, installs will be faster.

Your package will also have smaller carbon footprint.

Adding your package will not exceed size limits in resource constrained environments, like Serverless.

If bundle size is small, the load times for the final application will be faster.

Write minimal code needed for solving the problem.

Use package.json "files" field to only publish required files, thus removing unnecessary files.

[1]: https://docs.npmjs.com/cli/v7/configuring-npm/package-json#files

🔥 Consider moving TypeScript types to DefinitelyTyped. 🔥

If using TypeScript, publish sources and source maps in debug variant of your package using dist-tags.

Have minimal, or no dependencies!

Share tips for reducing publish/install size with packages you depend on.

Provide a variant of your package just for resource-constrained environment using a dist-tag.

@scope/package-name

@scope/package-name@node

: default variant - code for all platforms

: Node.js variant - Node.js specific code

Make your package tree shakeable (dead-code elimination).

Use named exports.

[1]: https://webpack.js.org/guides/tree-shaking/

Publish ESM version of your package.

Make your package side effects free.

Split code into multiple smaller modules.

It depends!

It's always good to have small install/publish/bundle size

JavaScript is dynamically typed programming language.

Between 15% to 38% of the bugs can be prevented by types.

[1]: https://earlbarr.com/publications/typestudy.pdf

[2]: https://www.reddit.com/r/typescript/comments/aofcik

Types are checked and errors are spotted only at the runtime.

Using types, IDEs can provide code editing features like code completion and parameter information.

[1]: https://2021.stateofjs.com/en-US/other-tools/#javascript_flavors

[2]: https://www.npmtrends.com/coffeescript-vs-elm-vs-flow-bin-vs-purescript-vs-reason-vs-typescript-vs-clojurescript

[3]: https://github.com/tc39/proposal-type-annotations

TypeScript is the most popular type system for JS.

ECMAScript proposal: Type Annotations

Either write your code in TypeScript or generate types from comments for your JavaScript code by running tsc.

The types can be linked in the "types" field in package.json

"types": "./dist/types.d.ts",

Or submit them to DefinitelyTyped to be published under @types organization on npm.

@types/your-package-name

[1]: https://github.com/DefinitelyTyped/DefinitelyTyped

It depends!

Your users will most likely need TypeScript types.

If your package code is in a language which compiles to JavaScript (like TypeScript), then you need to publish source code and source maps to help with debugging.

It helps your users to debug though readable code. It improves their understanding of your package, helping them unblock themselves or cut relevant bug reports or feature requests.

Enable generation of sourceMap files in your TypeScript Config

"sourceMap": true,

"inlineSourceMap": true,

OR

Include TypeScript source in your source maps

"inlineSources": true,

"sourceRoot": "src",

OR

[1]: https://www.typescriptlang.org/tsconfig

If your package code is in a language which compiles to JavaScript, do provide sources and source maps.

If it cuts into your install/publish size quota, release a debug variant using `debug` dist-tag.

Observability is the ability to measure a system's current state based on the data it generates, such as logs, metrics, and traces.

Observability helps developers build better, stable applications.

Back in mid-2010s, there were competing APIs like OpenTracing and OpenCensus. In 2019, they merged into OpenTelemetry.

You can add out-of-the-box support for OTel, or add instrumentation in an external package.

import { trace } from '@opentelemetry/api';

const tracer = trace.getTracer("name", "0.1.0");

const span = tracer.startSpan("span-name");

// do some work

span.end();

[1]: https://opentelemetry.io/docs/instrumentation/js/getting-started/

Add external instrumentation for your package, either in your npm scope or in Otel.

[1]: https://github.com/open-telemetry/opentelemetry-js-contrib

Trivikram Kamat

@trivikram

@trivikr

Slides: https://slides.com/trivikram/cascadiajs-publishing