NPM Packages & Distribution

Overview

JopiJS allows you to share and install modules just like any other Node.js library. However, unlike standard libraries that stay hidden in node_modules, JopiJS extracts modules directly into your src/ folder to allow for deep integration and easy overrides.

In this guide, you will learn:

The naming convention for JopiJS modules.
How to install a third-party module.
How modules are automatically extracted to your src/ folder.
How to publish your own module to NPM.

1. Naming Convention

For JopiJS to recognize an NPM package as a "Jopi Module", its name must follow a specific pattern:

Global packages: Must start with jopimod_ (e.g., jopimod_blog_system).
Scoped packages: The package name within the scope must start with jopimod_ (e.g., @my-org/jopimod_auth).

Why the prefix?
This prefix prevents JopiJS from accidentally trying to process standard JavaScript libraries (like lodash or react) as Jopi modules.

2. Installing a Module

Installing a Jopi module is a two-step process:

Step 1: `npm install`

Add the package to your project like any other dependency.

npm install @jopijs/jopimod_user_auth

Step 2: Extraction (`mod-check`)

After installation, the module must be extracted from node_modules to your src/ directory. This is usually handled automatically by a postinstall script in your root package.json.

package.json

{
  "scripts": {
    "postinstall": "npx jopi mod-check"
  }
}

3. How Extraction Works

When you run jopi mod-check, the following happens:

JopiJS scans your dependencies for the jopimod_ prefix.
It copies the source code from node_modules/ to your src/ folder.
It maps the names to a clean folder structure.

Visualizing the result:

NPM Package Name	Resulting Folder in `src/`
`jopimod_theme`	`src/mod_theme/`
`@jopijs/jopimod_uicore`	`src/mod_jopijs@uicore/`

Final Project Structure:

my-project/
├── package.json
├── node_modules/ ...
└── src/
    ├── mod_jopijs@uicore/    # Extracted from @jopijs/jopimod_uicore
    └── mod_theme/            # Extracted from jopimod_theme

The Jopi Advantage:
Because the source code is now in your src/ folder, you can read the code easily, and JopiJS can apply Overrides or Class Merging seamlessly.

4. Publishing Your Own Module

If you've built a great module and want to share it, follow these rules for the module's package.json:

Name: Must use the jopimod_ prefix.
Dependencies: Ensure your dependencies are listed in your package.json file.

src/mod_my_awesome_feature/package.json

{
  "name": "jopimod_my_awesome_feature",
  "version": "1.0.0",
  "description": "My first JopiJS module",
  "devDependencies": {
    "@jopijs/jopimod_uicore": "latest"
  }
}

Then, simply run npm publish from the module folder.


<Callout type="warning">
**Workspaces & Dependencies**  
Always list JopiJS modules in `devDependencies` instead of `dependencies`. This is because JopiJS leverages npm/yarn workspaces, and the module will be automatically added to the `workspaces` section of the project.
</Callout>

<Callout type="tip">
**Ignoring Workspaces**  
It is possible to use `{ "jopi": { "ignoreWorkspaces": true } }` in `package.json` to prevent the module from being added to the project workspaces. This is useful when managing multiple projects with identical modules.
</Callout>

---

## 5. Finding Modules

You can easily find community-contributed modules on the [NPM registry](https://www.npmjs.com/).

**Search Tip**: Use the keyword **`jopimod_`** in the NPM search bar to list all compatible JopiJS modules.