Package.json Configuration

Essential fields for npm packages:

{
  "name": "@scope/package-name",
  "version": "1.0.0",
  "description": "Clear description of what the package does",
  "main": "dist/index.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.esm.js",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist", "README.md", "LICENSE"],
  "scripts": {
    "build": "tsc && rollup -c",
    "test": "jest",
    "prepublishOnly": "npm run build && npm test"
  },
  "keywords": ["keyword1", "keyword2"],
  "author": "Your Name <email@example.com>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/username/repo.git"
  },
  "bugs": {
    "url": "https://github.com/username/repo/issues"
  },
  "homepage": "https://github.com/username/repo#readme",
  "peerDependencies": {
    "react": "^18.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

Publishing Workflow

Manual Publishing:

# Login to npm
npm login

# Test package locally first
npm pack
npm install ./package-name-1.0.0.tgz

# Publish (scoped packages need --access public)
npm publish --access public

Automated Publishing with CI/CD:

# GitHub Actions workflow
name: Publish to NPM

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'

      - run: npm ci
      - run: npm test
      - run: npm run build

      # Verify version matches tag
      - name: Verify version
        run: |
          TAG="${GITHUB_REF#refs/tags/v}"
          VERSION=$(node -p "require('./package.json').version")
          if [ "$TAG" != "$VERSION" ]; then
            echo "Version mismatch"
            exit 1
          fi

      # Publish with provenance
      - run: npm publish --access public --provenance
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

NPM Token Setup:

Use Granular Access Tokens (classic tokens are deprecated)
Set appropriate scopes and expiration
Store as NPM_TOKEN in GitHub Secrets

Semantic Versioning

Follow semver (major.minor.patch):

# Bug fixes (1.0.0 -> 1.0.1)
npm version patch

# New features (1.0.0 -> 1.1.0)
npm version minor

# Breaking changes (1.0.0 -> 2.0.0)
npm version major

# Push tags
git push origin main --tags

What to Exclude

Create .npmignore:

src/
tests/
*.test.js
.github/
.env
tsconfig.json
rollup.config.js

Or use files in package.json (recommended).

Chrome Extension Publishing

Manifest Validation

Ensure manifest.json meets store requirements:

{
  "manifest_version": 3,
  "name": "Extension Name",
  "version": "1.0.0",
  "description": "Clear description under 132 characters",
  "icons": {
    "16": "icons/icon16.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  },
  "permissions": ["storage"],
  "host_permissions": ["https://*.example.com/*"],
  "action": {
    "default_popup": "popup.html"
  }
}

Chrome Web Store Submission

Preparation:

Create high-quality icons (16x16, 48x48, 128x128)
Prepare promotional images (1280x800 or 640x400)
Write clear description and privacy policy
Test on multiple Chrome versions

Submission Process:

# Build production version
npm run build

# Create zip file
cd dist && zip -r ../extension.zip . && cd ..

# Upload to Chrome Web Store Developer Dashboard
# https://chrome.google.com/webstore/devconsole

Publishing Checklist:

Valid manifest.json (no errors in chrome://extensions)
All permissions justified in description
Privacy policy URL (required if collecting data)
Screenshots and promotional images
Category selection
Pricing and distribution settings

Extension Update Process

{
  "version": "1.0.1",
  "version_name": "1.0.1 - Bug fixes"
}

Chrome auto-updates extensions within 5 hours of publishing.

App Store Submission (iOS)

App Store Connect Preparation

Required Assets:

App icons (1024x1024 for App Store)
Screenshots for all device sizes
Privacy policy URL
Support URL

Info.plist Requirements:

<key>CFBundleShortVersionString</key>
<string>1.0.0</string>
<key>CFBundleVersion</key>
<string>1</string>
<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <false/>
</dict>

Submission via Xcode or Transporter:

# Using xcrun altool (deprecated, use App Store Connect API)
xcrun altool --upload-app -f app.ipa -u username -p app-specific-password

# Modern approach: Use App Store Connect API with EAS or Fastlane

Review Checklist:

Google Play Store Submission (Android)

Play Console Requirements

AAB (Android App Bundle) preferred over APK:

# Build release AAB
./gradlew bundleRelease

# Sign with keystore
jarsigner -verbose -sigalg SHA256withRSA -digestalg SHA-256 \
  -keystore my-release-key.jks app-release.aab alias_name

Store Listing Requirements:

App name (max 30 characters)
Short description (max 80 characters)
Full description (max 4000 characters)
Screenshots (2-8 per device type)
Feature graphic (1024x500)
Privacy policy URL

Release Tracks:

Internal testing - Up to 100 testers, instant updates
Closed testing - Up to 100,000 testers, review required
Open testing - Public, review required
Production - Full release, review required

Automated Play Store Publishing

# Example with Expo EAS
eas submit --platform android --latest

Release Notes Best Practices

NPM Package Changelog

Follow Keep a Changelog format:

# Changelog

## [1.2.0] - 2025-01-24

### Added

- New feature X for improved performance
- Support for TypeScript 5.0

### Changed

- Updated dependency Y to v3.0

### Fixed

- Bug causing crash on mobile devices

### Deprecated

- Function Z will be removed in v2.0

## [1.1.0] - 2025-01-10

...

App Store Release Notes

iOS (App Store Connect):

What's New in Version 1.2.0

• Added dark mode support
• Improved performance on older devices
• Fixed crash when uploading photos
• Minor bug fixes and improvements

Android (Play Console):

Version 1.2.0 - January 24, 2025

New:
- Dark mode support
- Offline mode for saved content

Improvements:
- Faster app startup
- Better battery usage

Fixes:
- Resolved photo upload crash

Version Management

Consistent Versioning Across Platforms

Package.json:

{
  "version": "1.2.0"
}

Expo app.json:

{
  "expo": {
    "version": "1.2.0",
    "ios": {
      "buildNumber": "12"
    },
    "android": {
      "versionCode": 12
    }
  }
}

Git Tags:

git tag v1.2.0
git push origin v1.2.0

Pre-release Versions

# NPM
npm publish --tag beta
npm install package@beta

# Expo
eas build --profile preview

Quality Assurance Before Publishing

Pre-publish Checklist

NPM:

Chrome Extension:

Mobile Apps:

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing: Record any new patterns or exceptions discovered.

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.

publishing-rules

Publishing Rules Skill

NPM Package Publishing