npm package: @rhcp/primer
Description: Primer, the Red Hat Customer Portal's shared front-end.  This package provides easy importing plus type definitions.
Latest version: 1.3.18

# Primer

Primer is the Red Hat Customer Portal's shared front-end.

This package is _not required_ to utilize Primer's JS libraries.  What this package provides is an easier way to import Primer's JS libraries, plus you'll get type definitions for those libraries.  The type definitions can be utilized by both TypeScript and non-TypeScript projects.

Primer is a modern replacement for Portal Chrome.

## Importing primer.js

There are two ways to import primer.js, with 

### Importing primer.js without `@rhcp/primer`

Primer's JS module can be imported with modern JS imports (ES Modules).

```js
import { session } from "/services/primer/js/primer.js";
```

This is the simplest (as in fewest moving parts) way to import primer.js.  However, importing directly from `/services/primer/js/primer.js` has some drawbacks.  It's a lot to type from memory, and you won't get type definitions.  If those are important to you, this package (`@rhcp/primer`) can help.

### Importing primer.js from `@rhcp/primer`

This package, `@rhcp/primer`, is available to any Customer Portal application that has a way to install NPM dependencies (using npm, yarn, or pnpm), and which includes a bundler (esbuild, webpack, rollup, etc).  If your application fits that bill, read on.

Use npm (or your favorite JS package manager) to install `@rhcp/primer` as a devDependency.

```
npm install -D @rhcp/primer
```

Once you've installed the devDependency, you can import it.

```js
import Primer from "@rhcp/primer";

// add PatternFly Elements' pfe-card to your app
Primer.pfe.include("pfe-card");
```

Under the hood, `@rhcp/primer` is extremely simple.  It's nothing but a JS file that re-exports `/services/primer/js/primer.js` (saving you some typing) and attaches TypeScript definition file (`.d.ts`).

#### Node package resolution

For `import Primer from "@rhcp/primer"` to work, your bundler must support resolving modules by NPM package name.

 - **esbuild**: no plugin needed
 - **webpack**: no plugin needed
 - **rollup**: [plugin-node-resolve](https://www.npmjs.com/package/@rollup/plugin-node-resolve)

Your mileage may vary with other bundlers.

Your bundler must support resolving modules by NPM package name, and must allow defining `/services/primer/js/primer.js` as an `external` module.

#### Marking `primer.js` as an external module

primer.js should never be bundled, and should always be imported directly from `/services/primer/js/primer.js`.  This module, `@rhcp/primer`, encapsulates that import, but your bundler will likely need extra configuration to avoid trying to bundle it.

##### `external` in esbuild

Use the [external](https://esbuild.github.io/api/#external) setting:

**CLI**
```
--external:"/services/primer/js/primer.js"
```

**JS** (in the object passed to esbuild.buildSync())
```js
external: ["/services/primer/js/primer.js"]
```

##### `external` in rollup

Use the [external](https://rollupjs.org/guide/en/#external) setting:

**CLI**
```
--external "/services/primer/js/primer.js"
```

**JS** (rollup.config.js)
```js
external: ["/services/primer/js/primer.js"]
```

##### `external` in webpack

Webpack requires quite a few settings to make this work.  Please send PRs if any of these recomendations need to change.

**JS** (webpack.config.js)
```js
target: ["web", "es6"],
experiments: {
  outputModule: true,
},
externalsType: "module",
externals: {
  "/services/primer/js/primer.js": "/services/primer/js/primer.js", 
}
```


[pfe]: https://patternflyelements.com/