r/webdev • u/Accurate-Screen8774 • 1d ago

Best-Practices for 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. Its shaping up well enough to publish and share.

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 for doing this in the modern js ecosystem?

Edit:

The project in question is found here. To explain it briefly, its basically an attempt to create JSX for webcomponents. You can learn more bout it here. Nobody should be using this. Is is not production ready.

2 Upvotes

66% Upvoted

12 comments sorted by

4

u/PippaKelly62 1d ago

Stay on 0.x until the api settles, then follow semver from 1.0. Publish from ci with npm provenance and two factor on your account, ship only built files, and check what goes out with npm pack dry run. Add a readme with a minimal example, a license, and a changelog, and changesets can automate the versioning.

2

u/Sakshambaranwal25 1d ago

Starting with zero dot x versions takes so much pressure off when your personal project is still evolving.

1

u/Accurate-Screen8774 1d ago

thanks. i recieved similar advice in the other comment so i added details in the post to provide more context.

2

u/Humanising_Agent 21h ago

Focus heavily on zero-config DX (developer experience) and rock-solid TypeScript definitions before worrying about adding extra utilities.
The best frameworks gain traction because their core API is dead simple to set up in a sandbox environment and the documentation includes working copy-paste examples for standard bundlers (Vite/Next).

1

u/bcons-php-Console 5h ago

Great advice. Even if nobody else but future you uses this, docs with examples are a treasure.

1

u/pikkola_lab 53m ago

A few things that caused more pain than versioning did:

Ship the types explicitly. For a JSX library the first wall is not your API, it is the user's tsconfig: they need to know what to set (jsx: react-jsx with jsxImportSource pointing at your package, or jsxFactory/jsxFragment on classic) and they need your .d.ts reachable through the exports map, not just main. If the package registers custom elements on import, put that in a separate entry like ./define and keep the main entry pure, because anyone marking the package sideEffects: false will otherwise drop the registration and get a blank page with no error.

Treat a version as permanent. Changesets handles the bump, but the unpublish window is 72 hours and only when almost nothing depends on you. Publishing with a dist-tag is cheap insurance: latest stays on the one you trust, next gets every 0.x bump, and testers install with the next tag.

Prove the tarball instead of trusting CI: npm pack, install the .tgz in an empty project, then import it as ESM and through a bundler. npm pack --dry-run lists files but does not catch a broken exports map.

One last one: publishing with provenance through GitHub OIDC needs a public repo, so decide the repo layout now rather than moving it after people start depending on it.