A Vitest util to get all exported APIs of a package and prevent unintended breaking changes.
npm i -D vitest-package-exports
Update your Vitest config:
export default defineConfig({
test: {
server: {
deps: {
inline: [
'vitest-package-exports',
],
},
},
},
})
A typical usage is to make a snapshot to freeze the exported APIs of a package:
import { fileURLToPath } from 'node:url'
import { expect, it } from 'vitest'
import { getPackageExportsManifest } from 'vitest-package-exports'
it('exports snapshot', async () => {
const manifest = await getPackageExportsManifest({
importMode: 'src', // or 'dist' or 'package'
cwd: fileURLToPath(import.meta.url),
})
expect(manifest.exports)
.toMatchInlineSnapshot(`
{
".": {
"getPackageExportsManifest": "function",
},
}
`)
})
Everytime you adding or remove the exported APIs, the snapshot will break and requires explicit review. This would help you to catch unintended breaking changes, or unintentional internal leaks.
For example, if I renamed the getPackageExportsManifest
function to getPackageExportsManifestRenamed
, the test will fail until I update the snapshot:
If you want a cleaner snapshot:
You can use js-yaml
to format the object:
import { fileURLToPath } from 'node:url'
import yaml from 'js-yaml' // <---
import { expect, it } from 'vitest'
import { getPackageExportsManifest } from 'vitest-package-exports'
it('exports snapshot', async () => {
const manifest = await getPackageExportsManifest({
importMode: 'src',
cwd: fileURLToPath(import.meta.url),
})
expect(yaml.dump(manifest.exports)) // <---
.toMatchInlineSnapshot(`
.:
getPackageExportsManifest: function
`)
})
Since this utility is only a function, you can compose it freely to fit your monorepo structure.
If you want to snapshot all packages in your pnpm monorepo, here is an example we use in VueUse:
import yaml from 'js-yaml'
import { x } from 'tinyexec'
import { describe, expect, it } from 'vitest'
import { getPackageExportsManifest } from 'vitest-package-exports'
describe('exports-snapshot', async () => {
const packages: { name: string, path: string, private?: boolean }[] = JSON.parse(
await x('pnpm', ['ls', '--only-projects', '-r', '--json']).then(r => r.stdout),
)
for (const pkg of packages) {
if (pkg.private)
continue
it(`${pkg.name}`, async () => {
const manifest = await getPackageExportsManifest({
importMode: 'src',
cwd: pkg.path,
})
await expect(yaml.dump(manifest.exports, { sortKeys: (a, b) => a.localeCompare(b) }))
.toMatchFileSnapshot(`./exports/${pkg.name.split('/').pop()}.yaml`)
})
}
})
This will create a file snapshot for each package in the ./exports
directory.
When getPackageExportsManifest
is called, it will:
- Find the
package.json
file in the current working directory. - Parse the
exports
field in thepackage.json
file. - Depend on the
importMode
, it will resolve the exports to the corresponding import path.
package
: Import from package name directly, for exampleimport('vitest/config')
dist
: Import the module from the definedexports
entry, for exampleimport('./dist/config.mjs')
src
: Import the module from thesrc
directory (replacedist
withsrc
), for exampleimport('./src/config.ts')
- This assume your codebase is structure as
src
->dist
with one-to-one mapping. If you have a custom build process, provideresolveSourcePath
option to write your own mapping logic.
- This assume your codebase is structure as
- For each entry, it will import the module at runtime to get the exports object. Essentially
Object.keys(await import(entry))
(so it's better to only use this in sandboxed environments like Vitest) - Return the manifest of the exported APIs.
Actually not necessary, this utility does not directly depend on Vitest, but it's designed to work with Vitest. Internally it use dynamic import()
to get the exports object, it would work best in Vitest as it will provide proper resolution of the import path, while also supporting your alias config if any.
I named this under vitest-
to give a clear expection. Feel free to use it in other context or even plain Node.js, but no guarantee from our side. Please do your own research.
MIT License © Anthony Fu