Skip to main content
Apps are currently in alpha. The feature works but is still evolving.

​
Overview

Once your app is built and tested locally, you have two paths for distributing it:
  • Deploy a tarball — upload your app directly to a specific Habib's CRM server for internal or private use.
  • Publish to npm — list your app in the Habib's CRM marketplace for any workspace to discover and install.
Both paths start from the same build step.

​
Building your app

Run the build command to compile your app and generate a distribution-ready manifest.json: 
yarn Habib's CRM build
This compiles TypeScript sources, transpiles logic functions and front components, and writes everything to .Habib's CRM/output/. Add --tarball to also produce a .tgz package for manual distribution or the deploy command.

​
Deploying to a server (tarball)

For apps you don’t want publicly available — proprietary tools, enterprise-only integrations, or experimental builds — you can deploy a tarball directly to a Habib's CRM server.

​
Prerequisites

Before deploying, you need a configured remote pointing to the target server. Remotes store the server URL and authentication credentials locally in ~/.Habib's CRM/config.json. Add a remote: 
yarn Habib's CRM remote add --api-url https://your-Habib's CRM-server.com --as production

​
Deploying

Build and upload your app to the server in one step: 
yarn Habib's CRM deploy
# To deploy to a specific remote:
# yarn Habib's CRM deploy --remote production

​
Sharing a deployed app

Tarball apps are not listed in the public marketplace, so other workspaces on the same server won’t discover them by browsing. To share a deployed app:
  1. Go to Settings > Applications > Registrations and open your app
  2. In the Distribution tab, click Copy share link
  3. Share this link with users on other workspaces — it takes them directly to the app’s install page
The share link uses the server’s base URL (without any workspace subdomain) so it works for any workspace on the server.
Sharing private apps is an Enterprise feature. Go to Settings > Admin Panel > Enterprise to enable it.

​
Version management

To release an update:
  1. Bump the version field in your package.json
  2. Run yarn Habib's CRM deploy (or yarn Habib's CRM deploy --remote production)
  3. Workspaces that have the app installed will see the upgrade available in their settings

​
Publishing to npm

Publishing to npm makes your app discoverable in the Habib's CRM marketplace. Any Habib's CRM workspace can browse, install, and upgrade marketplace apps directly from the UI.

​
Requirements

  • An npm account
  • The Habib's CRM-app keyword in your package.json keywords array (already included when you scaffold with create-Habib's CRM-app)
{
  "name": "Habib's CRM-app-postcard-sender",
  "version": "1.0.0",
  "keywords": ["Habib's CRM-app"]
}

​
Marketplace metadata

The defineApplication() config supports optional fields that control how your app appears in the marketplace. Use logoUrl and screenshots to reference images from the public/ folder:
src/application-config.ts
export default defineApplication({
  universalIdentifier: '...',
  displayName: 'My App',
  description: 'A great app',
  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
  logoUrl: 'public/logo.png',
  screenshots: [
    'public/screenshot-1.png',
    'public/screenshot-2.png',
  ],
});
See the defineApplication accordion in the Building Apps page for the full list of marketplace fields (author, category, aboutDescription, websiteUrl, termsUrl, etc.).

​
Publish

yarn Habib's CRM publish
To publish under a specific dist-tag (e.g., beta or next): 
yarn Habib's CRM publish --tag beta

​
How marketplace discovery works

The Habib's CRM server syncs its marketplace catalog from the npm registry every hour. You can trigger the sync immediately instead of waiting: 
yarn Habib's CRM catalog-sync
# To target a specific remote:
# yarn Habib's CRM catalog-sync --remote production
The metadata shown in the marketplace comes from your defineApplication() config — fields like displayName, description, author, category, logoUrl, screenshots, aboutDescription, websiteUrl, and termsUrl.
If your app does not define an aboutDescription in defineApplication(), the marketplace will automatically use your package’s README.md from npm as the about page content. This means you can maintain a single README for both npm and the Habib's CRM marketplace. If you want a different description in the marketplace, explicitly set aboutDescription.

​
CI publishing

Use this GitHub Actions workflow to publish automatically on every release (uses OIDC): 
name: Publish
on:
  release:
    types: [published]

permissions:
  contents: read
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24"
          registry-url: https://registry.npmjs.org
      - run: yarn install --immutable
      - run: npx Habib's CRM build
      - run: npm publish --provenance --access public
        working-directory: .Habib's CRM/output
For other CI systems (GitLab CI, CircleCI, etc.), the same three commands apply: yarn install, yarn Habib's CRM build, then npm publish from .Habib's CRM/output.
npm provenance is optional but recommended. Publishing with --provenance adds a trust badge to your npm listing, letting users verify the package was built from a specific commit in a public CI pipeline. See the npm provenance docs for setup instructions.

​
Installing apps

Once an app is published (npm) or deployed (tarball), workspaces can install it through the UI. Go to the Settings > Applications page in Habib's CRM, where both marketplace and tarball-deployed apps can be browsed and installed. You can also install apps from the command line: 
yarn Habib's CRM install