r/learnjavascript • • 2d ago

Publishing a JS framework

Im working on a project for myself. Its an unreviewed, unaudited and far from finished. It started of as a person curiosity and evolved from there.

Im asking because if i publish something on NPM, there are strict controls around versioning for which i havent burdened myself on my own projects (but clearly important when making something for a wider community). I also wonder if im overlooking any other details.

I wonder what best practices there are for something like this. Should i be publishing new versions with CI/CD? Are there any tips or advice on doing this in the modern js package ecosystem?

5 Upvotes

6 comments sorted by

3

u/GiggleSamurai 2d ago

Publish it as 0.x: under semver a 0.y.z version means the API can still change at any time, so you aren't locking yourself in, and check `npm pack --dry-run` (or set the `files` field) so only the built code ships. A version number can only ever be published once, so publishing from CI on a git tag (GitHub Actions with npm trusted publishing) keeps your tags, changelog and npm in sync.

1

u/Discordbothost 2d ago

Test the package a user will actually install: run npm pack, install the .tgz into a fresh example app, and run the README example there. That catches missing build files and broken imports your repo's tests can miss.

1

u/DickBrainTime 1d ago

The part I'd decide before automating releases is your public compatibility contract: which import paths are supported (package exports), ESM-only vs ESM+CJS, whether TypeScript types resolve correctly, and your minimum Node/browser versions. If this framework wraps another library, think about whether it belongs in peerDependencies so consumers don't end up with two copies of the runtime.

CI can build and test every commit, but I wouldn't publish to npm on every merge while the API is still moving. Make publishing a deliberate, versioned release step. Add a small consumer fixture that imports the package and type-checks it in each module format you claim to support. That tends to catch compatibility breaks earlier than tests inside the framework repo. Is this meant for Node, browsers, or both?

1

u/Alternative-Host-210 21h ago

One thing I'd add from a teaching perspective: give the README example an expected result, not just installation commands and code. What should someone see when it works, and which bits are ordinary JavaScript versus conventions introduced by your framework?

Since it's still experimental, I'd also state what isn't supported yet. That helps someone distinguish their own mistake from a feature you haven't built.

What is the smallest task your framework makes easier? That would be a useful starting point for the first tutorial.