HowToCreateAPackage

How to create a package

Packages are the building blocks of which an application is composed. They can contain code, UI components, styles, services, translation files etc. At their core, they are simply Node packages (opens in a new tab) with a few extensions.

Note Application packages are packages like all others. They just have a few additional capabilities.

Background information

Every locally developed package must contain a package.json and a build.config.mjs. The package.json file is required by Node and PNPM, while the build.config.mjs is used to implement our framework specific extensions (services etc.).

By convention, packages are placed into src/packages/../<PACKAGE_NAME>. However, they can be placed anywhere within the src directory: every package.json in the source directory is detected by pnpm as part of the workspace (see pnpm-workspace.yaml), and all packages in the workspace may reference each other (more details (opens in a new tab)).

Required files

We will create a package called hello-world that exports a simple function:

1
{
2
    "name": "hello-world",
3
    "private": true
4
}

1
import { defineBuildConfig } from "@open-pioneer/build-support";
2

3
// The empty object is the minimal configuration.
4
// We're not going to use any custom features from the Open Pioneer Trails framework for now.
5
export default defineBuildConfig({});

Run pnpm install to ensure that pnpm knows about our new package. pnpm provides powerful tools to work with the local workspace, we can use this to verify our setup: you can run pnpm ls -r --depth -1 (optionally with --json) to print all local packages.

1
$ pnpm ls -r --depth -1 --json
2
# ...
3
#     {
4
#         "name": "hello-world",
5
#         "path": "<PROJECT_PATH>/src/packages/hello-world",
6
#         "private": true
7
#     },
8
# ...

Entry point

Since we want to provide a plain function to other packages, we must create a module from which that function can be imported. Modules (i.e. .js or .ts files) that are designed to be imported from other packages (i.e. they are not private) are also called entry points. We only need a single one, which we will call index.ts:

1
export function greet(target = "World") {
2
    console.info(`Hello ${target}!`);
3
}

Next, we will edit our package.json to declare index.ts as our package’s main entry point (opens in a new tab). This will ensure that when someone imports "hello-world", they will receive the exports from index.ts.

1
{
2
    "name": "hello-world",
3
    "private": true,
4
    "main": "index.ts"
5
}

Note
We’re currently not enforcing most imports between packages. That means that you’re technically able to import internal modules that happen to live in the package’s directory. In the future, we will likely implement a lint to prevent this to enforce clean usage of dependencies.

For the time being, we recommend consulting a package’s documentation for public entry points and not relying on implementation details of other packages.

Using the package

The last step is to actually use the function from one of our apps. For that, we’re going to extend this project’s empty app in src/apps/empty.

First, start the development server:

1
$ pnpm run dev

Then, open the test site for the empty app, usually at http://localhost:5173/sites/empty/ (opens in a new tab).

In order to use the new package, it must be declared as a dependency in your app’s package.json:

1
{
2
    "name": "empty",
3
    "private": true,
4
    "dependencies": {
5
        "@chakra-ui/react": "catalog:",
6
        "@open-pioneer/runtime": "catalog:",
7
        "sample-package": "workspace:*",
8
        // Add this line:
9
        "hello-world": "workspace:*"
10
    }
11
}

Note
The workspace: protocol instructs pnpm to always install the referenced package from the local workspace. Installation in this case means simply linking the packages together: node_modules will contain links to the dependencies in the source directory (read more (opens in a new tab)).

At this point, your browser will likely display an error because the dependency cannot be found. We have to run pnpm install after editing the dependencies, then reload your browser: the error will be gone.

Finally, we can use greet function from the hello-world package. We’ll simply edit the app.ts:

1
import { createCustomElement } from "@open-pioneer/runtime";
2
import * as appMetadata from "open-pioneer:app";
3
import { AppUI } from "./AppUI";
4

5
// Imports the function from `hello-world/index.ts`
6
import { greet } from "hello-world";
7

8
// Simply calls the function when the module is loaded.
9
greet();
10

11
const Element = createCustomElement({
12
    component: AppUI,
13
    appMetadata
14
});
15

16
customElements.define("empty-app", Element);

Open your browser’s console to see the result:

message printed to the console