Publishing Extensions to npm

Share your extension with other Chatons users by publishing it to npm.

Prerequisites:

• A working extension (see Extensions Tutorial)
• An npm account (npmjs.com)
• For terminal publishing: npm CLI installed (npm -v)

---

Package Name Requirements

Your extension's npm package name must match this pattern:

@username/chatons-extension-name

The regex enforced by Chatons:

^@[^/]+\/chatons-extension-[a-z0-9][a-z0-9-]*$

Valid examples:

• @john/chatons-extension-my-notes
• @acme/chatons-extension-weather
• @thibaut/chatons-extension-telegram

Invalid examples:

• my-notes (missing @scope/chatons-extension- prefix)
• @john/notes (missing chatons-extension- prefix)
• @john/chatons-extension- (no name after prefix)

---

Required Files

Your extension folder must contain:

File	Required	Description
chaton.extension.json	Yes	Extension manifest
package.json	Yes	npm package metadata
Built UI assets	Yes	Usually a dist/ folder containing your HTML entry and bundled assets
README.md	Recommended	Usage instructions for users
LICENSE	Recommended	License file (MIT recommended)

---

Step-by-Step Publishing

1. Verify Your Extension Works

Test everything locally:

cd ~/.chaton/extensions/@yourname/chatons-my-notes

# Validate manifest
jq . chaton.extension.json > /dev/null && echo "Manifest OK"

# Validate package.json
jq . package.json > /dev/null && echo "Package OK"

Restart Chatons and confirm your extension loads without errors.

2. Ensure package.json Is Complete

{
  "name": "@yourname/chatons-my-notes",
  "version": "1.0.0",
  "description": "A note-taking extension for Chatons",
  "author": "Your Name",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourname/chatons-my-notes"
  },
  "keywords": ["chatons", "extension", "notes"]
}

Important: The name in package.json and the id in chaton.extension.json must follow the same @user/chatons-extension-* pattern. They should match.

3. Ensure Versions Match

Both files must have the same version:

jq .version chaton.extension.json
# "1.0.0"

jq .version package.json
# "1.0.0"

4. Log In to npm

npm login
# Follow the prompts for username, password, and email

# Verify login
npm whoami

5. Check Package Contents

npm pack --dry-run

This shows what files will be included in the package. Make sure your built UI assets, manifest, and runtime files are listed.

6. Publish

cd ~/.chaton/extensions/@yourname/chatons-my-notes
npm publish --access public

The --access public flag is required for scoped packages (@username/...).

7. Verify

npm info @yourname/chatons-my-notes

Visit https://npmjs.com/package/@yourname/chatons-my-notes to see your published extension.

---

Publishing from Chatons UI

Chatons also supports publishing from the Extensions panel:

1. Go to Extensions in the sidebar
2. Find your extension in the list
3. Click the publish action
4. Enter your npm token if prompted
5. If your package.json has a build script, Chatons runs npm run build first
6. In packaged desktop builds, Chatons runs Electron's embedded Node runtime together with a bundled npm CLI, so this flow does not depend on node or npm being available in the GUI process PATH
7. Chatons runs npm publish for you

Note: Only locally installed extensions (not npm-installed ones) can be published this way. The extension must have a valid package.json and its installSource must be localPath.

---

Updating Your Extension

To publish an update:

1. Make your code changes
2. Bump the version in both chaton.extension.json and package.json
3. Follow semver:
   • Patch (1.0.0 -> 1.0.1): Bug fixes
   • Minor (1.0.0 -> 1.1.0): New features, backward compatible
   • Major (1.0.0 -> 2.0.0): Breaking changes
4. Publish again:

   npm publish --access public

Users can see updates available in the Chatons Extensions panel and install them.

---

Troubleshooting

Error	Solution
Invalid package name	Name must match @user/chatons-extension-* pattern
package.json not found	Create a package.json in your extension directory
You must be logged in	Run npm login first
403 Forbidden	Package name might already exist, or you lack publish rights
Only locally installed extensions can be published	You are trying to publish an npm-installed extension. Publish from the source directory instead.

---

Pre-Publish Checklist

• Extension works locally in Chatons
• chaton.extension.json is valid JSON
• package.json is valid JSON with correct name
• Versions match in both files
• README.md exists with usage instructions
• No hardcoded secrets or API keys in code
• All declared capabilities are actually used
• Console has no errors (F12)
• Extension survives a Chatons restart
• npm whoami succeeds
• npm pack --dry-run includes all needed files

---

Related

• Extensions Tutorial -- Build your first extension
• Extensions API -- API reference
• Extensions Overview -- Manifest and capabilities