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?
Maintaining Your Company’s Open-Source Ecosystem
…or how to make great npm packages for the mere mortal.
1
Let’s start with a little story, shall we?
2
+
+
3
It worked great!
However…
4
5
Making my own packages?
6
7
8
That worked great!
- Cherry-picking my packages on a need basis
- No more copy/pasting the same snippets from project to project!
9
Do you know who faced a similar story around the same period?
10
11
Then
->
Now 12
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?
13
Let’s get started
shall we?
14
I’m Lucie Haberer
a.k.a. lihbr
15
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
16
Let’s make it interactive
A little~
17
18
Package Ecosystems
19
Package Ecosystems
Packages
->
Ecosystem of packages
20
A better way to think about making packages as an organization or an individual.
21
What’s a Package
Ecosystem?
22
A package ecosystem is all the packages under the responsibility of an entity, whether it’s an individual, a company, etc.
23
Prismic
->
CMS
Users
->
SDKs (packages)
24
What’s a Package Ecosystem?
25
What’s a Package Ecosystem?
26
That’s my definition of a package ecosystem
But let’s specify a few things…
27
What’s a Package Ecosystem?
- Ecosystems can be private
- foo
28
I worked at a bank™
29
What’s a Package Ecosystem?
- Ecosystems can be private
- Ecosystems with just one package are valid
30
That’s where considering packages as an ecosystem helps
31
Making an exception
-^
You’re growing an ecosystem that will support you in your journey
32
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
33
34
Why would I want to grow my own ecosystem, or even make packages?
35
36
37
Abstracting things
38
39
This works for other kind of companies!
40
I worked at a bank™
41
Internal auth service
->
Auth package
42
Maintain SDKs
->
Built with Vite
43
Why Making Packages?
Packages are quite handy to abstract code you use often:
- Small libraries
- Helpers
- Configuration
46
Don’t abstract prematurely
Abstraction never comes for free, neither does creating packages.
47
Why Making Packages?
- Abstracting things
- Forking an existing packages
- Creating a new technology
- etc.
48
We’re building packages to make our developer nicer, and our software stronger
49
50
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
51
It’s fine if you don’t want or need to create packages yet.
But it’s always cool to know how to.
52
53
How Packages Work?
54
How Packages Work?
- PHP packages
- Deno modules
- Rust crates
- Ruby gems
- etc.
55
npm packages
56
How npm packages work, and their intricacies
57
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
58
It’s two things!
59
npm
60
etc.
tl;dr; they all claim to do something better than npm (that's pretty much true)
61
npm
npm is also an online database.
- A registry
- Where packages can be published
- Where packages can be downloaded
62
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.com64
I worked at a bank™
65
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
66
->
->
67
package.json
…our package definition
68
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"
}
}69
Two fields are mandatory
70
package.json
Mandatory name field.
- Our package name
- Anything kebab case will be fine
- Can be scoped!
71
@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
72
package.json
Mandatory version field.
- Our package version
- foo
- bar
73
74
package.json
75
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
76
77
Let’s now see more package-oriented fields
78
package.json
A package is about delivering code.
-^
Entry points, what’s accessible on our package.
79
package.json
{
"name": "my-package",
"version": "0.0.1",
"main": "./dist/index.js",
"scripts": { ... },
"dependencies": { ... },
"devDependencies": { ... }
}-^
const myPackage = require("my-package");80
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";81
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";82
package.json
{
"name": "my-package",
"version": "0.0.1",
"main": "./dist/index.js",
"module": "./dist/index.mjs",
"exports": {
".": {
"require": {
"default": "./dist/index.js"
},
"import": {
"default": "./dist/index.mjs"
}
}
},
"scripts": { ... },
"dependencies": { ... },
"devDependencies": { ... }
}83
Which ones are we supposed to use?
84
package.json
Not straightforward to answer, but "basically":
exportsonly if you want to be future-facing, and only future-facingmain,module, andexportsif you want (or need to) be compatible with most setup
85
package.json
Package code entry points:
main, default entry point (CJS or ESM)module, ESM-specific entry pointexports, modern entry points, more flexible
86
package.json
{
"name": "my-package",
"version": "0.0.1",
"main": "./dist/index.js",
"module": "./dist/index.mjs",
"exports": {
".": {
"require": {
"types": "./dist/index.d.ts", // Make sure it appears first in export maps!
"default": "./dist/index.js" // ...otherwise it can cause issues with some tools.
},
"import": {
"types": "./dist/index.d.ts",
"default": "./dist/index.mjs"
}
}
},
"types": "./dist/index.d.ts",
"scripts": { ... },
"dependencies": { ... },
"devDependencies": { ... }
}87
package.json
{
"name": "my-package",
"version": "0.0.1",
"main": "./dist/index.js",
"module": "./dist/index.mjs",
"exports": {
".": {
"require": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
},
"import": {
"types": "./dist/index.d.ts",
"default": "./dist/index.mjs"
}
}
},
"types": "./dist/index.d.ts",
"bin": {
"my-package": "./bin/cli.js"
},
"scripts": { ... },
"dependencies": { ... },
"devDependencies": { ... }
}88
package.json
{
"name": "my-package",
"version": "0.0.1",
"main": "./dist/index.js",
"module": "./dist/index.mjs",
"exports": {
".": {
"require": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
},
"import": {
"types": "./dist/index.d.ts",
"default": "./dist/index.mjs"
}
}
},
"types": "./dist/index.d.ts",
"bin": {
"my-package": "./bin/cli.js"
},
"files": ["src"],
"scripts": { ... },
"dependencies": { ... },
"devDependencies": { ... }
}89
90
{
"name": "@prismicio/client",
"version": "7.0.0",
"exports": {
".": {
"require": { "types": "./dist/index.d.ts", "default": "./dist/index.cjs" },
"import": { "types": "./dist/index.d.ts", "default": "./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": { ... }
}91
package.json
Types of dependencies:
dependenciesdevDependencies
- foo
Only package’s dependencies are installed when it’s installed, devDependencies are ignored
92
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"
}
}93
package.json
Types of dependencies:
dependencies, required to run the packagedevDependencies, required to build the packagepeerDependencies
foo
94
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"
}
}95
package.json
Main things to consider:
- Required
nameandversionfields - Entry points declaration
- Proper dependency declaration
96
package.json
Things I omitted:
-
engine -
type(nos!) repository,sideEffects,publishConfig, etc.
- foo
More on the documentation: https://docs.npmjs.com/cli/v9/configuring-npm/package-json
97
Maintaining Packages
98
99
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.
100
If the package works fine enough for you and others, it’s already great!
101
102
Maintaining Packages
Regular maintenance:
- Fixing bugs if any
- Maintaining dependencies (updating them)
- foo
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.
103
104
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
105
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
- foo
Be a great citizen and use the npm deprecate command.
106
Maintaining Your Company’s Open-Source Ecosystem
…or how to make great npm packages for the mere mortal.
107
We discussed:
- Package ecosystems, for organizations and individuals
- NPM packages and their intricacies
- Package maintenance tips
108
All the Info
Everything from this talk & more:
-> lucie.red/nuxtnation-23
Twitter:
-> lucie.red/twitter
Mastodon:
-> lucie.red/mastodon
109
110