Skip to content

PUBLISHING.md

Latest commit

 

History

History
178 lines (141 loc) · 3.77 KB

PUBLISHING.md

File metadata and controls

178 lines (141 loc) · 3.77 KB

NPM Publishing Checklist

1. Create NPM Account (One-time setup)

If you need to create the @embedly organization:

# Sign up at https://www.npmjs.com/signup
# Then create organization at https://www.npmjs.com/org/create
# Organization name: embedly

Login to NPM

npm login
# Enter your username, password, and email
# Or use: npm login --auth-type=web (for GitHub SSO)

2. Pre-Publish Checks

✅ Verify package.json

  • Correct package name: @embedly/nextjs
  • Version is set (1.0.0 for first release)
  • Description is clear
  • Repository URL is correct
  • Keywords are comprehensive
  • License is set (MIT)
  • Files field lists only necessary files

✅ Security Check

# Make sure no .env files are tracked
git ls-files | grep -E "\.env"
# Should return nothing

# Check .gitignore includes:
# - .env.local
# - .env*.local
# - node_modules
# - dist (build output should be generated, not committed)

✅ Build the package

npm install
npm run build

# Verify dist/ folder was created with:
# - index.js
# - index.d.ts
# - EmbedlyEmbed.js
# - EmbedlyEmbed.d.ts
# - server.js
# - server.d.ts
# - types.js
# - types.d.ts

✅ Test the package locally

# Create a tarball to see exactly what will be published
npm pack

# This creates embedly-nextjs-1.0.0.tgz
# Extract and inspect:
tar -tzf embedly-nextjs-1.0.0.tgz

# Should contain:
# - package/dist/
# - package/README.md
# - package/CONTRIBUTING.md
# - package/package.json

# Test in your test app:
cd test_app
npm install ../embedly-nextjs-1.0.0.tgz
# Verify it works

3. Publishing Steps

For a scoped package (@embedly/nextjs):

First-time publish:

cd /path/to/embedly-nextjs

# Dry run to see what would be published
npm publish --dry-run

# Publish as public (scoped packages are private by default)
npm publish --access public

Subsequent updates:

# Update version in package.json (or use npm version)
npm version patch  # 1.0.0 -> 1.0.1
# or
npm version minor  # 1.0.0 -> 1.1.0
# or
npm version major  # 1.0.0 -> 2.0.0

# Commit the version bump
git add package.json
git commit -m "Bump version to X.X.X"
git push

# Publish
npm publish --access public

# Tag the release on GitHub
git tag v1.0.0
git push origin v1.0.0

4. Post-Publish Steps

Verify publication

# Check on NPM
open https://www.npmjs.com/package/@embedly/nextjs

# Test installation in a fresh project
mkdir test-install
cd test-install
npm init -y
npm install @embedly/nextjs

Update documentation

  • Add npm badge to README: ![npm version](https://img.shields.io/npm/v/@embedly/nextjs.svg)
  • Update main Embedly docs to reference this package
  • Announce on social media / blog

Set up GitHub

  • Enable GitHub Discussions
  • Add issue templates
  • Set up branch protection on main
  • Add topics to repository: embedly, oembed, nextjs, react, embed

5. Troubleshooting

"You do not have permission to publish @embedly/nextjs"

  • You need to be part of the @embedly organization on NPM
  • Ask an org admin to add you, or create the org if it doesn't exist

"Package name already exists"

"This package has been marked as private"

  • Add --access public to the publish command
  • Or add "publishConfig": { "access": "public" } to package.json

Quick Reference Commands

# Login
npm login

# Build
npm run build

# Test package contents
npm pack
tar -tzf embedly-nextjs-1.0.0.tgz

# Publish
npm publish --access public

# Version bump and publish
npm version patch
git push && git push --tags
npm publish --access public