@pandev-srl/better-ui NPM

Better UI Assets - NPM Package Publishing Guide

This repository contains the compiled JavaScript assets for the Better UI library, published as @pandev-srl/better-ui on NPM.

Prerequisites

Node.js and npm installed
Yarn package manager
Access to publish to @pandev-srl organization on NPM
direnv installed for environment management

Initial Setup

1. Install direnv

macOS (using Homebrew):

brew install direnv

Ubuntu/Debian:

sudo apt install direnv

2. Configure your shell

Add the following to your shell configuration file (.bashrc, .zshrc, etc.):

eval "$(direnv hook bash)"  # for bash
# or
eval "$(direnv hook zsh)"   # for zsh

3. Setup NPM Token

Login to npmjs.com
Go to Access Tokens in your account settings
Generate a new Automation token (or Publish token)
Copy the generated token

4. Configure Environment

Copy the environment example file:

cp .envrc.example .envrc

Edit .envrc and replace my-token with your actual NPM token:

export NPM_TOKEN="npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Allow direnv to load the environment:

direnv allow

Publishing Process

Step 1: Version Bump

Update the version in package.json. Follow Semantic Versioning:

Patch (bug fixes): 0.1.0 → 0.1.1
Minor (new features): 0.1.0 → 0.2.0
Major (breaking changes): 0.1.0 → 1.0.0

# Edit package.json manually, or use npm version command:
npm version patch    # for patch version bump
npm version minor    # for minor version bump
npm version major    # for major version bump

Step 2: Build Assets

Compile the assets using Vite:

yarn build

This will generate the compiled files in the dist/ directory:

dist/better_ui.js (ES module)
dist/better_ui.umd.cjs (UMD/CommonJS)

Step 3: Publish to NPM

Ensure you're in the better_ui_assets directory and publish:

npm publish

The package will be published with public access due to the publishConfig setting in package.json.

Complete Publishing Workflow

Here's the complete workflow in one go:

# 1. Ensure environment is loaded
direnv reload

# 2. Verify NPM authentication
npm whoami

# 3. Update version (choose one)
npm version patch  # or minor/major

# 4. Build assets
yarn build

# 5. Publish
npm publish

# 6. Verify publication
npm info @pandev-srl/better-ui

Package Information

Package Name: @pandev-srl/better-ui
Current Version: 0.1.0
Registry: npmjs.com
Access: Public
License: MIT

Files Included in Publication

The following files are included when publishing:

package.json - Package metadata and dependencies
dist/ - Compiled JavaScript assets
LICENSE - MIT license file
README.md - This documentation

Files excluded (via .gitignore patterns):

src/ - Source files
node_modules/ - Dependencies
Development configuration files

Troubleshooting

Authentication Issues

If you get authentication errors:

Verify your NPM token is correct:

echo $NPM_TOKEN

Check if you're logged in:

npm whoami

npm login

Permission Issues

If you get permission errors for the @pandev-srl organization:

Ensure you're a member of the @pandev-srl organization on NPM
Verify you have publish permissions
Contact the organization owner if needed

Build Issues

If the build fails:

Install dependencies:

yarn install

Clear any cache:

rm -rf dist/
yarn build

Version Conflicts

If you get version conflicts:

Check the current published version:

npm info @pandev-srl/better-ui version

Ensure your local version is higher than the published version
Update package.json version accordingly

Best Practices

Always test locally before publishing
Follow semantic versioning strictly
Review changes in the dist/ folder after building
Tag releases in git to track versions
Update changelog for significant releases
Test installation after publishing:
```
npm install @pandev-srl/better-ui
```

Support

For issues related to:

Package publishing: Check NPM documentation
Build process: Review Vite configuration in vite.config.js
Library functionality: See main Better UI documentation

@hotwired/stimulus @hotwired/turbo-rails vite

0.1.1

6 months ago

0.1.0

6 months ago