NPM Publishing

How to configure and publish FlexUI (or your own FlexUI-based library) to the npm registry.

On this page

Prerequisites package.json Setup .npmignore Login & Publish Versioning Automated Releases Scoped Packages

Prerequisites

An npm account — create one at npmjs.com/signup
Node.js ≥ 18 and npm ≥ 9
The package name must be unique on the registry (or scoped to your org)

package.json Setup

A well-configured package.json is required for the package to work correctly after installation.

package.json

{
  "name": "flexui",
  "version": "1.0.0",
  "description": "A modern frontend framework by Fluxenite",
  "author": "Fluxenite <fluxenieab@gmail.com>",
  "license": "MIT",
  "type": "module",

  // Entry points
  "main": "./src/core/index.js",
  "exports": {
    ".":             "./src/core/index.js",
    "./router":      "./src/router/index.js",
    "./seo":         "./src/seo/index.js",
    "./server":      "./src/server/index.js",
    "./hooks":       "./src/hooks/index.js",
    "./components":  "./src/components/index.js"
  },

  // CLI binary
  "bin": { "flexui": "./src/cli/index.js" },

  // Files included in the published package
  "files": ["src", "README.md", "CHANGELOG.md"],

  "keywords": ["framework", "frontend", "ssr", "ssg", "fluxenite"],
  "repository": {
    "type": "git",
    "url": "https://github.com/fluxenite/flexui.git"
  },
  "homepage": "https://flexui.dev",
  "bugs": "https://github.com/fluxenite/flexui/issues"
}

Use "files" instead of .npmignore

The files field is a whitelist approach — only the listed paths are included. This is safer than .npmignore because new files won't accidentally be published.

.npmignore

If you prefer a blacklist, create a .npmignore file. It follows the same syntax as .gitignore.

.npmignore

*.test.js
*.spec.js
__tests__/
.cache/
example/
scripts/
.github/
tsconfig.json
jest.config.*

1
Log in to npm
```
npm login
```
You will be prompted for your username, password, and OTP (if 2FA is enabled).
2
Dry run to verify what will be published
```
npm publish --dry-run
```
Review the file list. Make sure no secrets, test files, or large binaries are included.
3
Publish
```
npm publish
```
The package is now live at https://www.npmjs.com/package/flexui.

Versioning

FlexUI follows Semantic Versioning. Use npm version to bump the version and automatically create a git tag.

# Bug fix
npm version patch   # 1.0.0 → 1.0.1

# New feature (backwards compatible)
npm version minor   # 1.0.0 → 1.1.0

# Breaking change
npm version major   # 1.0.0 → 2.0.0

# Then publish
npm publish

Automated Releases (GitHub Actions)

Automate publishing on every tagged commit with a GitHub Actions workflow:

.github/workflows/publish.yml

name: Publish to npm

on:
  push:
    tags: ['v*']

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Set NPM_TOKEN as a repository secret in GitHub → Settings → Secrets → Actions. Generate the token at npmjs.com → Account → Access Tokens.

Scoped Packages

Publish under your npm org or username with a scope to avoid name conflicts:

// package.json
{ "name": "@fluxenite/flexui" }

# Publish public scoped package
npm publish --access public