Maintaining Your Company’s Open-Source Ecosystem

…or how to make great npm packages for the mere mortal.

Maintaining Your Company’s Open-Source Ecosystem

…or how to make great npm packages for the mere mortal.

Let’s start with a little story, shall we?

It worked great!

However…

Modern Times Charlie Chaplin GIF

Making my own packages?

lihbr utils Nuxt preview

lihbr utils Netlify preview

That worked great!

Cherry-picking my packages on a need basis
No more copy/pasting the same snippets from project to project!

Do you know who faced a similar story around the same period?

NuxtLabs team

Then

Now

Let’s talk packages:

What’s a package ecosystem, and why would you have your own?
How packages work with NPM?
What package maintenance looks like?

Let’s get started
shall we?

I’m Lucie Haberer

a.k.a. lihbr

About Me

I’m from France

Started development with MediaWiki
I worked at a bank™
Developer Experience Engineer at Prismic
Proud Nuxt contributor & team member

Let’s make it interactive

A little~

Have you ever published a package?

Yes

lucie.red/pkg

lucie.red/nopkg

0

Package Ecosystems

Packages

Ecosystem of packages

A better way to think about making packages as an organization or an individual.

What’s a Package
Ecosystem?

A package ecosystem is all the packages under the responsibility of an entity, whether it’s an individual, a company, etc.

Prismic

CMS

Users

SDKs (packages)

What’s a Package Ecosystem?

That’s my definition of a package ecosystem

But let’s specify a few things…

What’s a Package Ecosystem?

Ecosystems can be private

I worked at a bank™

What’s a Package Ecosystem?

Ecosystems can be private
Ecosystems with just one package are valid

That’s where considering packages as an ecosystem helps

Making an exception

You’re growing an ecosystem that will support you in your journey

Package Ecosystem Recap

Defines packages under the responsibility of an entity
Can be private or public
Can hold as many or as few packages as needed

Why would I want to grow my own ecosystem, or even make packages?

Abstracting things

Prismic

API

Users

@prismicio/client

This works for other kind of companies!

I worked at a bank™

Internal auth service

Auth package

Maintain SDKs

Built with Vite

vite-plugin-sdk on npm

vite-plugin-sdk on npm

Nuxt extends example from Docus GitHub

Why Making Packages?

Packages are quite handy to abstract code you use often:

Small libraries
Helpers
Configuration

Don’t abstract prematurely

Abstraction never comes for free, neither does creating packages.

Why Making Packages?

Abstracting things

Forking an existing packages
Creating a new technology
etc.

We’re building packages to make our developer nicer, and our software stronger

Why Making Packages?

Small packages also make a difference.

Easier to start with as an author
More easily made at any company
Smaller surface and scope than big codebases
Small APIs can easily be battle-tested
Give us confidence to build on trusty foundations

It’s fine if you don’t want or need to create packages yet.

But it’s always cool to know how to.

How Packages Work?

PHP packages
Deno modules
Rust crates
Ruby gems
etc.

npm packages

How npm packages work, and their intricacies

How Packages Work?

Few disclaimers before we embark:

This is not about which bundler or linter to use
- Come chat with me during breaks if you want those
Yes I’ll talk about writing a package.json, but no worries

It’s two things!

npm

etc.

tl;dr; they all claim to do something better than npm (that's pretty much true)

npm

npm is also an online database.

A registry
Where packages can be published
Where packages can be downloaded

npmjs.com screenshot

npmjs.com

npm

You can configure npm to resolve your dependencies across multiple registries.

# .npmrc

# Fetch `@lihbr` packages from GitHub registry
@lihbr:registry=https://npm.pkg.github.com

# Fetch `@my-company` packages from My Company registry
@my-company:registry=https://npm.pkg.my-company.com

I worked at a bank™

npm

A CLI
An online database (registry)

Don’t like the CLI? You can change it
Don’t want to be on the public registry? Use another

package.json

…our package definition

package.json

{
	"name": "elk.zone",
	"version": "0.5.0",
	"scripts": {
		"build": "nuxi build",
		"dev": "nuxi dev --port 5314",
		"generate": "nuxi generate"
	},
	"dependencies": {
		"@vueuse/core": "^9.10.0",
		"blurhash": "^2.0.4",
		"masto": "^5.5.0"
	},
	"devDependencies": {
		"eslint": "^8.31.0",
		"nuxt": "^3.0.0",
		"prettier": "^2.8.2",
		"typescript": "^4.9.4"
	}
}

Two fields are mandatory

package.json

Mandatory name field.

Our package name
Anything kebab case will be fine
Can be scoped!

`@prismicio/client`

Represents a user or an organization

You can only publish to scopes you have access to

Hint, at a glance, who's the package publisher

package.json

Mandatory version field.

Our package version

Can you use `2.3` as a version number?

Yes

lucie.red/true

lucie.red/false

0 package.json

npm version command showcased

package.json

Mandatory version field.

Our package version
Has to be a valid SemVer number
- A versioning convention
- Reflects kind of changes between two versions
- Learn more at semver.org

Let’s now see more package-oriented fields

package.json

A package is about delivering code.

Entry points, what’s accessible on our package.

package.json

{
	"name": "my-package",
	"version": "0.0.1",
	"main": "dist/index.js",
	"scripts": { ... },
	"dependencies": { ... },
	"devDependencies": { ... }
}

const myPackage = require("my-package");

package.json

{
	"name": "my-package",
	"version": "0.0.1",
	"main": "dist/index.js",
	"module": "dist/index.mjs",
	"scripts": { ... },
	"dependencies": { ... },
	"devDependencies": { ... }
}

import myPackage from "my-package";

package.json

{
	"name": "my-package",
	"version": "0.0.1",
	"main": "dist/index.js",
	"module": "dist/index.mjs",
	"scripts": { ... },
	"dependencies": { ... },
	"devDependencies": { ... }
}

import myPackage from "my-package";

package.json

{
	"name": "my-package",
	"version": "0.0.1",
	"main": "dist/index.js",
	"module": "dist/index.mjs",
	"exports": {
		".": {
			"require": "./dist/index.js",
			"import": "./dist/index.mjs"
		}
	},
	"scripts": { ... },
	"dependencies": { ... },
	"devDependencies": { ... }
}

Which ones are we supposed to use?

package.json

Not straightforward to answer, but "basically":

exports only if you want to be future-facing, and only future-facing
main, module, and exports if you want (or need to) be compatible with most setup

package.json

Package code entry points:

main, default entry point (CJS or ESM)
module, ESM-specific entry point
exports, modern entry points, more flexible

package.json

{
	"name": "my-package",
	"version": "0.0.1",
	"main": "dist/index.js",
	"module": "dist/index.mjs",
	"exports": {
		".": {
			"require": "./dist/index.js",
			"import": "./dist/index.mjs"
		}
	},
	"types": "dist/index.d.ts",
	"scripts": { ... },
	"dependencies": { ... },
	"devDependencies": { ... }
}

package.json

{
	"name": "my-package",
	"version": "0.0.1",
	"main": "dist/index.js",
	"module": "dist/index.mjs",
	"exports": {
		".": {
			"require": "./dist/index.js",
			"import": "./dist/index.mjs"
		}
	},
	"types": "dist/index.d.ts",
	"bin": {
		"my-package": "bin/cli.js"
	},
	"scripts": { ... },
	"dependencies": { ... },
	"devDependencies": { ... }
}

package.json

{
	"name": "my-package",
	"version": "0.0.1",
	"main": "dist/index.js",
	"module": "dist/index.mjs",
	"exports": {
		".": {
			"require": "./dist/index.js",
			"import": "./dist/index.mjs"
		}
	},
	"types": "dist/index.d.ts",
	"bin": {
		"my-package": "bin/cli.js"
	},
	"files": ["src"],
	"scripts": { ... },
	"dependencies": { ... },
	"devDependencies": { ... }
}

{
	"name": "@prismicio/client",
	"version": "7.0.0",
	"exports": {
		".": {
			"require": "./dist/index.cjs",
			"import": "./dist/index.js"
		},
		"./package.json": "./package.json"
	},
	"main": "dist/index.cjs",
	"module": "dist/index.js",
	"types": "dist/index.d.ts",
	"files": [
		"dist",
		"src"
	],
	"scripts": { ... },
	"dependencies": { ... },
	"devDependencies": { ... }
}

package.json

Types of dependencies:

dependencies
devDependencies

Only package’s dependencies are installed when it’s installed, devDependencies are ignored

package.json

{
	"name": "my-package",
	"version": "0.0.1",
	"main": "dist/index.js",
	"module": "dist/index.mjs",
	"scripts": {
		"build": "vite build"
	},
	"dependencies": { ... },
	"devDependencies": {
		"vite": "^4.0.4"
	}
}

package.json

Types of dependencies:

dependencies, required to run the package
devDependencies, required to build the package
peerDependencies

foo

package.json

{
	"name": "vue-router",
	"version": "4.1.6",
	"main": "index.js",
	"module": "dist/vue-router.mjs",
	"scripts": { ... },
	"dependencies": { ... },
	"devDependencies": { ... },
	"peerDependencies": {
		"vue": "^3.2.0"
	}
}

package.json

Main things to consider:

Required name and version fields
Entry points declaration
Proper dependency declaration

package.json

Things I omitted:

engine
type (no s!)
repository, sideEffects, publishConfig, etc.

More on the documentation: https://docs.npmjs.com/cli/v9/configuring-npm/package-json

Maintaining Packages

Have you ever opened an issue or a feature request on an open-source project?

Yes

lucie.red/open

lucie.red/never

0 Maintaining Packages

People expect a lot from open-source packages.

It’s fine if you don’t support TypeScript from the get-go
It’s fine if you don’t have both CJS and ESM
It’s fine if you don’t write TSDocs
etc.

If the package works fine enough for you and others, it’s already great!

Inspire from other open-source projects

Things that work great for others, might work great for you!

100

Maintaining Packages

You can learn a lot this way.

Do crazy things through the .github folder
Automate your release process with tools like Standard Version CLI
Update dependencies with tools like VSCode Version Lens

101

Maintaining Packages

Regular maintenance:

Fixing bugs if any
Maintaining dependencies (updating them)

Helps ensuring your package keeps working and is easy to work with.

At Prismic, once a week if there are issues, otherwise, once a month.

102

103

Maintaining Packages

Evolving?

Adding new features and changing existing ones
No rule of thumb for that
Adding small features can often be done as-is

For bigger ones and breaking changes, planning is encouraged
- RFCs work great for us at Prismic
- Nuxt 3 <NuxtLink /> RFC example

104

Maintaining Packages

A package can die.

Maybe its functionalities are now native, or not relevant anymore
Maybe it has been replaced with something better
Maybe no one wants to maintain it anymore

Be a great citizen and use the npm deprecate command.

105

Maintaining Your Company’s Open-Source Ecosystem

…or how to make great npm packages for the mere mortal.

106

We discussed:

Package ecosystems, for organizations and individuals
NPM packages and their intricacies
Package maintenance tips

107

All the Info

Everything from this talk & more:

-> lucie.red/amsterdam-23

Twitter:

-> lucie.red/twitter

Mastodon:

-> lucie.red/mastodon

108

Thanks!

lucie.red/amsterdam-23 — lucie.red/twitter — lucie.red/mastodon

109

Maintaining Your Company’s Open-Source Ecosystem

Let’s start with a little story, shall we?

Maintaining Your Company’s Open-Source Ecosystem

Let’s start with a little story, shall we?

It worked great!

Making my own packages?

That worked great!

Do you know who faced a similar story around the same period?

Let’s talk packages:

Let’s get startedshall we?

I’m Lucie Haberer

About Me

Let’s make it interactive

Have you ever published a package?

0

0

Package Ecosystems

Package Ecosystems

A better way to think about making packages as an organization or an individual.

What’s a PackageEcosystem?

What’s a Package Ecosystem?

What’s a Package Ecosystem?

That’s my definition of a package ecosystem

What’s a Package Ecosystem?

I worked at a bank™

What’s a Package Ecosystem?

That’s where considering packages as an ecosystem helps

Package Ecosystem Recap

Why would I want to grow my own ecosystem, or even make packages?

Abstracting things

This works for other kind of companies!

I worked at a bank™

Why Making Packages?

Don’t abstract prematurely

Why Making Packages?

We’re building packages to make our developer nicer, and our software stronger

Why Making Packages?

It’s fine if you don’t want or need to create packages yet.

How Packages Work?

How Packages Work?

npm packages

How npm packages work, and their intricacies

How Packages Work?

npm

npm

npm

I worked at a bank™

npm

package.json

package.json

Two fields are mandatory

package.json

@prismicio/client

package.json

Can you use 2.3 as a version number?

0

0

package.json

package.json

Let’s now see more package-oriented fields

package.json

package.json

package.json

package.json

package.json

Which ones are we supposed to use?

package.json

package.json

package.json

package.json

package.json

package.json

package.json

package.json

package.json

package.json

package.json

Maintaining Packages

Have you ever opened an issue or a feature request on an open-source project?

0

Let’s get started
shall we?

What’s a Package
Ecosystem?

`@prismicio/client`

Can you use `2.3` as a version number?