NPM Deep Dive

Setup

• Node 16
• pnpm

Tutorial

1. Basic NPM Package Setup

Ref: https://github.com/aaronklinker-st/npm-package-deep-dive/commit/2cb150cf162f446cb8efcd06763b30435b8afcb8

Three main files to be aware of:

1. The library's entrypoint

   npm-package-deep-dive/lib/index.js

   Lines 1 to 13 in 2cb150c

   	/**
   	* Returns the username, profile url, and avatar URL for all contributors of a repo.
   	*/
   	export async function getContributors({ owner, repo }) {
   	const res = await fetch(`https://api.github.com/repos/${owner}/${repo}/contributors`);
   	const json = await res.json();
   	return json.map((user) => ({
   	username: user.login,
   	profileUrl: user.html_url,
   	avatarUrl: user.avatar_url,
   	}));
   	}

2. The Website's script where getContributors is used

   npm-package-deep-dive/web/src/main.ts

   Lines 1 to 25 in 2cb150c

   	import "./style.css";
   	// @ts-expect-error
   	import { getContributors } from "@aklinker1/github-contributors";
   	const app = document.querySelector<HTMLDivElement>("#app")!;
   	const listItem = (contributor: any) => `
   	<li>
   	<img src="${contributor.avatarUrl}" />
   	<a href="${contributor.profileUrl}" target="_blank">${contributor.username}</a>
   	</li>
   	`;
   	async function render() {
   	const contributors = await getContributors({
   	owner: "denoland",
   	repo: "deno",
   	});
   	app.innerHTML = `<ul>
   	${contributors.map(listItem).join("")}
   	</ul>`;
   	}
   	render();

3. The CLI's entrypoint where getContributors is used

   npm-package-deep-dive/cli/index.js

   Lines 1 to 19 in 2cb150c

   	import { getContributors } from "@aklinker1/github-contributors";
   	import asciify from "asciify-image";
   	async function main() {
   	console.log("\nLoading...\n");
   	const contributors = await getContributors({ owner: "denoland", repo: "deno" });
   	const images = await Promise.all(
   	contributors.map(({ avatarUrl }) => asciify(avatarUrl, { fit: "box", width: 20 }))
   	);
   	for (let i = 0; i < contributors.length; i++) {
   	const { username, profileUrl } = contributors[i];
   	console.log(`\x1b[1m${username}\x1b[0m - \x1b[2m${profileUrl}\x1b[0m`);
   	console.log(images[i], "\n");
   	}
   	}
   	main();

Next, publish the first version of the NPM package.

pnpm publish --no-git-checks

Install in the web and cli package, make sure they work.

2. Supporting Node 16

Ref: https://github.com/aaronklinker-st/npm-package-deep-dive/commit/78a2e29dd2ffe405de497dcd046dd48e55c8efde

Node 16 doesn't include the fetch API. If we want to support Node 16, we'll need to use a library, like ofetch.

Diff: https://github.com/aaronklinker-st/npm-package-deep-dive/commit/78a2e29dd2ffe405de497dcd046dd48e55c8efde#

1. Install ofetch and use it in the lib/index.js file
2. Publish a new version
3. Install latest version in web and cli packages, make sure they work

3. Include CJS Support

Ref: https://github.com/aaronklinker-st/npm-package-deep-dive/commit/ef8444364c865aad4d0b5ae1b9db4c310eec54b8 & https://github.com/aaronklinker-st/npm-package-deep-dive/commit/58facc2f71c3c96a2b61d26bee73caea0df1a887

The package will not work in a CJS project.

Return to presentation to talk about modules.

So lets convert our CLI to CJS, and publish both a CJS, ESM, and for kicks and giggles, IIFE.

Follow this diff: https://github.com/aaronklinker-st/npm-package-deep-dive/commit/ef8444364c865aad4d0b5ae1b9db4c310eec54b8

Then:

1. Install TSUP
2. Add build and prepublish script

   npm-package-deep-dive/lib/package.json

   Lines 15 to 16 in 58facc2

   	"build": "tsup index.js --format cjs,esm,iife --sourcemap --global-name githubContributors",
   	"prepublish": "pnpm build"

3. Discuss flags for build script
4. Make additional changes to the package.json https://github.com/aaronklinker-st/npm-package-deep-dive/commit/58facc2f71c3c96a2b61d26bee73caea0df1a887#diff-1e946220773aef913945326261b7ee8d08b8ec29ccc66ef7c348950439212ffb
5. Publish new version
6. Show that it works with cli, a CJS project, and web, an ESM project

4. Adding Declaration File

Ref: https://github.com/aaronklinker-st/npm-package-deep-dive/commit/9375762bda5daa015afc37017cd587cff9223e78

Return to slides talk about typescript.

1. Add declaration file
2. Publish new version
3. Show how types are now provided to consumers and on NPM

5. Full TypeScript Package

Ref: https://github.com/aaronklinker-st/npm-package-deep-dive/commit/0a1694b022e4e9a8e8454034e717ecce35153785

Fully convert the project to typescript: https://github.com/aaronklinker-st/npm-package-deep-dive/commit/0a1694b022e4e9a8e8454034e717ecce35153785

1. Convert the JS file to TS
2. Delete the declaration file
3. Build declaration file
4. Include package types field
5. Add TS config file