Build a Canopus applet from scratch

NODE_ENV=development
CANOPUS_HOSTNAME=localhost.leap365.com

~/projects/
├── canopus                      # the platform, built above
└── canopus-applet-you            # what you are about to create

{
  "name": "canopus-applet-you",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "packageManager": "yarn@4.9.2",
  "types": "canopus.augment.d.ts",
  "scripts": {
    "dev": "canopus applet dev",
    "build": "canopus applet build",
    "typecheck": "tsc -b"
  },
  "canopus": {
    "links": []
  },
  "resolutions": {
    "@canopus/build": "portal:../canopus/packages/build",
    "@canopus/build/@canopus/devcert": "portal:../canopus/third-party/devcert",
    "@canopus/foundation": "portal:../canopus/packages/foundation",
    "@canopus/shared": "portal:../canopus/packages/shared",
    "@canopus/tsconfig": "portal:../canopus/packages/tsconfig"
  },
  "dependencies": {
    "@canopus/foundation": "^1.0.22",
    "@starlens/react": "0.1.32",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@canopus/build": "^1.0.28",
    "@canopus/tsconfig": "^1.0.0",
    "@types/react": "^19",
    "@types/react-dom": "^19",
    "typescript": "^5.8"
  }
}

nodeLinker: node-modules

npmScopes:
  "leap":
    npmRegistryServer: https://artifactory.leapaws.com.au/artifactory/api/npm/LEAP/
  "starlens":
    npmRegistryServer: https://artifactory.leapaws.com.au/artifactory/api/npm/LEAP/

# @canopus/build declares svelte as a peer for its svelte-loader rule, which it only
# installs when stack is "svelte". A React applet must not have that peer, so the one
# warning about it is discarded rather than worked around.
logFilters:
  - pattern: "*doesn't provide svelte*"
    level: discard

CI=false
CLI_DEBUG=false

# Left blank on purpose - these two are per-developer, and belong in .env.local.
# NODE_ENV is the build mode. CANOPUS_HOSTNAME is the hostname the applet is served
# on: the dev certificate is generated for it, and the shell must be on the same one.
NODE_ENV=
CANOPUS_HOSTNAME=

NODE_ENV=development
CANOPUS_HOSTNAME=localhost.leap365.com

node_modules/
dist/

# Generated per-applet by the canopus CLI: dev certs, generated types, tmp config
.canopus/
logs/
.tmp.webpack.config.mjs

# Per-developer overrides; .env holds the committed defaults
.env.local

*.tsbuildinfo

# Yarn 4 with nodeLinker: node-modules - keep releases/plugins/patches, ignore the rest
.yarn/*
!.yarn/patches
!.yarn/plugins
!.yarn/releases
.pnp.*

{
  "extends": "@canopus/tsconfig/base",
  "compilerOptions": {
    "types": ["@canopus/tsconfig/types"],
    // composite is what the canopus CLI's type generation needs, and it forces emit -
    // so send that emit somewhere ignored. Without an outDir, `tsc -b` writes .js beside
    // every source file and webpack then resolves those instead, breaking the build.
    "outDir": ".canopus/tsc",
    "composite": true,
    "jsx": "react-jsx"
  },
  "include": ["src", "canopus.augment.d.ts", ".canopus/types"]
}

import { createApplet } from "@canopus/build";

export default createApplet({
  // The Module Federation scope: unique across every applet the shell may load, and a
  // valid JavaScript identifier. Convention is <teamprefix>_<appletname>.
  name: "ws_you",

  // "./main" is the entry the shell calls on startup. Every other key you add later is
  // a module the host can resolve on its own - that is how widgets are found.
  exposes: {
    "./main": "./src/main",
  },

  // The port `yarn dev` serves on. --port overrides it; with neither, applets fall
  // back to 4500.
  devPort: 3001,

  // React comes from the host as a Module Federation shared singleton. Declaring the
  // stack is what stops this applet bundling a second copy - two Reacts in one page is
  // a broken page.
  stack: "react",
});

import { applet } from "@canopus/foundation";

/**
 * The smallest complete applet: a class extending applet.Applet, exported as a single
 * instance from the module the build exposes as "./main".
 *
 * The shell instantiates nothing. It imports this default export and calls the hooks.
 */
class WorkshopApplet extends applet.Applet {
  async onLoad() {
    // Your own setup: mount locations, stores, subscriptions. Other applets may not
    // have loaded yet, so do not talk to them here.
    this.logger.info("onLoad");
  }

  async onLoaded() {
    // Every applet has loaded by now - the place to reach for another applet's API.
    this.logger.info("onLoaded");
  }

  async onUnload() {
    // Release anything acquired above. Mountables are torn down by the host.
    this.logger.info("onUnload");
  }
}

const workshopApplet = new WorkshopApplet();

export default workshopApplet;

import type ws_you from "./src/main";

declare module "@canopus/foundation/registry" {
  interface AppletRegistry {
    ws_you: typeof ws_you;
  }
}

import { useState } from "react";

import styles from "./App.module.css";

/**
 * Nothing in here knows it is running inside a host. Props arrive from the mount
 * location, and the host owns the element this renders into.
 */
export default function App() {
  const [count, setCount] = useState(0);

  return (
    <div className={styles.root}>
      <button type="button" className={styles.button} onClick={() => setCount((n) => n + 1)}>
        ws_you WorkShop · {count}
      </button>
    </div>
  );
}

/*
 * A .module.css is locally scoped by the build's css-modules rule, so nothing in here
 * can leak into the shell's DOM - or into another applet's.
 *
 * This mounts into the appbar, whose background is the shell's navbar colour.
 * --stl-navbar-main-heading is the foreground Starlens pairs with it: white in the light
 * theme, the legible inverse in dark. The #fff fallback covers a host that has not
 * loaded the tokens yet.
 */
.root {
  display: flex;
  gap: 8px;
  color: var(--stl-navbar-main-heading, #fff);
}

.button {
  padding: 0 8px;
  border: 1px solid currentcolor;
  border-radius: 8px;
  background: transparent;
  font: inherit;
  cursor: pointer;
}

.button:hover {
  background: rgb(255 255 255 / 12%);
}

import { applet, layout } from "@canopus/foundation";

import App from "./app/App";

class WorkshopApplet extends applet.Applet {
  // The lazy alternative, for when the component is heavy enough to be worth its own
  // request: lazyReactMountable code-splits it, so nothing in ./app/App is fetched
  // until the host actually mounts it. Swap the two and drop the import above.
  //
  // readonly #greeting = layout.lazyReactMountable(() => import("./app/App").then((m) => m.default), {
  //   priority: 10_000,
  // });

  // Eager, and what this applet uses: App is imported at the top and ships in the
  // main chunk. There is no helper for this one, because there is nothing to help with
  // - a mountable is a plain object, and addToMountLocation takes a function returning it.
  readonly #greeting = (): layout.ReactMountable => ({
    type: "react",
    component: App,
    // Orders mountables within one location, highest first. 10_000-90_000 is the
    // range applets may use; outside it is reserved for the host.
    priority: 10_000,
  });

  async onLoad() {
    this.logger.info("onLoad");

    this.addToMountLocation("appbar-middle", this.#greeting);
  }

  async onLoaded() {
    this.logger.info("onLoaded");
  }

  async onUnload() {
    this.logger.info("onUnload");
  }
}

const workshopApplet = new WorkshopApplet();

export default workshopApplet;

import { environment, http } from "@canopus/foundation";
import { use } from "react";

import styles from "./MatterCount.module.css";

interface Matter {
  matterId: string;
  fileNumber: string;
  firstDescription: string;
}

interface RecentMatters {
  totalCount: number;
  matters: Matter[];
}

// Module scope is fine here: the shell sets the environment during bootstrap, before it
// imports a single applet. Never hard-code a host, though - this is what makes one build
// run against dev, test and live.
const apiUrl = `${environment.env().endpoints.docsCoreApi}/api/v2/recentmatters?maxRecordsToReturn=100`;

const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

const fetchRecentMatters = async () => {
  // The three seconds are only so the fallback is on screen long enough to watch.
  // Take the delay out once you have seen it.
  await delay(3_000);

  // No response.ok check: http.get returns a spread of the Response, and ok/status
  // live on Response's prototype, so they do not survive the spread. A failed request
  // rejects here instead - and use() throws that to the nearest error boundary.
  const response = await http.get(apiUrl);

  return response.json<RecentMatters>();
};

// Called once, here - not inside the component. use() reads the same promise on every
// render, and a fresh one per render would suspend for ever.
const recentMatters = fetchRecentMatters();

// One component, two mountables. The appbar has room for a number and nothing else, so
// the list is opt-in: the widget asks for it, the appbar does not.
export function MatterCount({ showList = false }: { showList?: boolean }) {
  // Suspends until the promise settles. No loading state, no useEffect, no
  // setState-after-unmount to worry about.
  const { totalCount, matters } = use(recentMatters);

  return (
    <>
      <span>Matters: {totalCount}</span>
      {showList && (
        <ul className={styles.list}>
          {matters.map((matter) => (
            // matterId, not the index: it is the stable identity the API already gives you.
            <li key={matter.matterId} className={styles.item}>
              {matter.fileNumber} — {matter.firstDescription}
            </li>
          ))}
        </ul>
      )}
    </>
  );
}

/*
 * The list fills the width of the column it is in and takes whatever height is left
 * under the counter, scrolling inside itself rather than stretching its container. A
 * widget owns a cell the dashboard sized; nothing an applet renders may decide how much
 * room it gets.
 *
 * flex: 1 claims the remaining height. min-height: 0 is what makes it *scroll* rather
 * than grow past the cell - a flex item's floor is its content height until you say
 * otherwise, and that one line is the difference between a scrollbar and an overflow.
 * align-self: stretch fills the width even though the column centres its other children.
 */
.list {
  flex: 1;
  min-height: 0;
  align-self: stretch;

  /* Definite width to truncate against, padding counted inside it. */
  width: 100%;
  box-sizing: border-box;

  /* min-width: 0 is the one that is easy to miss. A flex item will not shrink below
     its own content by default (min-width: auto), so a single long description widens
     this list, then the column, then pushes the widget out of its cell - and the
     ellipsis below never fires, because there is nothing constraining the text. */
  min-width: 0;

  overflow-x: hidden;
  overflow-y: auto;

  margin: 0;
  padding-left: 18px;
  text-align: left;
}

/*
 * Truncate the long ones rather than letting them run: nowrap keeps a matter on one
 * line, the constrained width above gives ellipsis something to measure against, and
 * min-width: 0 stops this item claiming its content width in turn.
 */
.item {
  min-width: 0;
  max-width: 100%;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

import { Suspense, useState } from "react";

import styles from "./App.module.css";
import { MatterCount } from "./MatterCount";

export default function App() {
  const [count, setCount] = useState(0);

  return (
    <div className={styles.root}>
      {/* Only the count waits on the request - the button renders straight away. */}
      <Suspense fallback={<span>Loading...</span>}>
        <MatterCount />
      </Suspense>
      <button type="button" className={styles.button} onClick={() => setCount((n) => n + 1)}>
        ws_you WorkShop · {count}
      </button>
    </div>
  );
}

import { StlButton, StlFlex } from "@starlens/react";
import { Suspense, useState } from "react";

import { MatterCount } from "../../app/MatterCount";
import styles from "./Counter.module.css";

/**
 * Starlens is a separate concern from Canopus: an applet needs none of it to run, and
 * the host shares @starlens/* as Module Federation singletons exactly as it shares
 * React - so using it costs you no bundle weight and cannot fork the design system.
 */
export default function Counter() {
  const [count, setCount] = useState(0);

  // height: 100% on the column is what gives the list a height to take the rest of.
  return (
    <StlFlex direction="column" gap="medium" align="center" className={styles.root}>
      <p>Count: {count}</p>
      <StlButton variant="primary" onClick={() => setCount((n) => n + 1)}>
        Increment
      </StlButton>
      {/* MatterCount suspends, so it needs a boundary here too - the one in App.tsx
          belongs to that mountable and does nothing for this one. */}
      <Suspense fallback={<span>Loading...</span>}>
        {/* The widget has room for the matters themselves; the appbar asks for the
            count alone. */}
        <MatterCount showList />
      </Suspense>
    </StlFlex>
  );
}

/*
 * Fill the cell the dashboard gave this widget. Without a height here the column is only
 * as tall as its contents, and "the rest of the height" is nothing to divide up.
 *
 * min-width: 0 for the same reason it appears in MatterCount.module.css: this column is
 * itself a flex item, and without it the longest line inside decides how wide the widget
 * is - which is how a truncated list still ends up overflowing its cell.
 */
.root {
  height: 100%;
  min-width: 0;
}

import { applet, layout } from "@canopus/foundation";

import Counter from "./components/Counter";

/**
 * Its own Applet subclass in its own exposed module. The difference from ./src/main is
 * only how the host finds it: provideMountable offers the mountable *by name* rather
 * than registering it at a shell mount location.
 *
 * The name defaults to this module, which is what the dashboard looked it up by - pass
 * one explicitly only if a single module offers several mountables.
 */
class CounterWidget extends applet.Applet {
  private handleWidgetMount(): layout.ReactMountable {
    return {
      type: "react",
      component: Counter,
      priority: 10_000,
    };
  }

  async onLoad() {
    this.provideMountable(this.handleWidgetMount);
  }
}

const counterWidget = new CounterWidget();

export default counterWidget;

  exposes: {
    "./main": "./src/main",
    "./CounterWidget": "./src/widgets/CounterWidget",
  },

import { applets } from "@canopus/foundation";

async onLoaded() {
  const dashboard = applets.getApplet("canopus_dashboard");
  // Do not store the reference - ask again when you need it.
}

{
  "name": "canopus-applet-you-angular",
  "resolutions": {
    // A copy, not a symlink - see above. Everything else stays portal:.
    "@canopus/angular": "file:../canopus/packages/angular",
    "@canopus/build": "portal:../canopus/packages/build",
    "@canopus/build/@canopus/devcert": "portal:../canopus/third-party/devcert",
    "@canopus/foundation": "portal:../canopus/packages/foundation",
    "@canopus/shared": "portal:../canopus/packages/shared",
    "@canopus/tsconfig": "portal:../canopus/packages/tsconfig"
  },
  "dependencies": {
    "@angular/common": "^21.2.21",
    "@angular/core": "^21.2.21",
    "@angular/platform-browser": "^21.2.21",
    "@canopus/angular": "^1.0.0",
    "@canopus/foundation": "^1.0.22",
    "rxjs": "^7.8.1"
  },
  "devDependencies": {
    "@angular/compiler": "^21.2.21",
    "@angular/compiler-cli": "^21.2.21",
    "@babel/core": "^7",
    "@canopus/build": "^1.0.28",
    "@canopus/tsconfig": "^1.0.0",
    "@ngtools/webpack": "^21.0.0",
    "babel-loader": "^9",
    "typescript": "^5.8",
    "webpack": "^5"
  }
}

{
  "extends": "@canopus/tsconfig/base",
  "compilerOptions": {
    "types": ["@canopus/tsconfig/types"],
    "outDir": ".canopus/tsc",
    "composite": true,
    // Angular's field semantics predate the ES class-fields spec, and target es2022 in
    // the base config would otherwise turn this on. Every Angular CLI tsconfig sets it
    // false; decorated fields misbehave without it. experimentalDecorators is already
    // true in @canopus/tsconfig/base.
    "useDefineForClassFields": false
  },
  "angularCompilerOptions": {
    "strictTemplates": true,
    "strictInjectionParameters": true
  },
  "include": ["src", "canopus.augment.d.ts", ".canopus/types"]
}

import path from "node:path";
import { createRequire } from "node:module";
import { fileURLToPath } from "node:url";

import { angularHmrBridgeLoader, createApplet } from "@canopus/build";
import { AngularWebpackPlugin } from "@ngtools/webpack";
import type { Compiler, RuleSetRule } from "webpack";

const here = path.dirname(fileURLToPath(import.meta.url));
const require = createRequire(import.meta.url);

// True for the two swc-loader rules @canopus/build installs for .ts/.tsx.
const isSwcRule = (rule: RuleSetRule | "..." | null | undefined | false | 0 | ""): boolean => {
  if (!rule || rule === "...") {
    return false;
  }

  const use = (rule as RuleSetRule).use;

  return (
    typeof use === "object" && use !== null && !Array.isArray(use) && "loader" in use && use.loader === "swc-loader"
  );
};

// The query @ngtools/webpack appends when it rewrites a component's styleUrl into an
// import. It reads back that module's exported *string*, so a component stylesheet has
// to be built differently from the applet's own CSS.
const NG_RESOURCE = /\?ngResource/;

/**
 * Makes the child compilation behind a styleUrl able to have an entry at all.
 *
 * webpack overwrites a child compiler's `compilation` taps with its parent's, throwing
 * away the dependency factory EntryPlugin registered. In an ordinary build the parent
 * has entries of its own and registers the same one anyway - but an applet's entry is
 * {}, because Module Federation exposes the modules instead. Without this the build
 * fails with "No dependency factory available for this dependency type: EntryDependency".
 */
class EntryDependencyFactoryPlugin {
  apply(compiler: Compiler) {
    // Must come from the same copy of webpack the build is running, which a plain
    // import cannot promise - hence the throwaway dependency.
    const EntryDependency = compiler.webpack.EntryPlugin.createDependency("", {}).constructor;

    compiler.hooks.compilation.tap("EntryDependencyFactoryPlugin", (compilation, { normalModuleFactory }) => {
      compilation.dependencyFactories.set(EntryDependency as never, normalModuleFactory);
    });
  }
}

export default createApplet({
  name: "ws_you_ng",
  exposes: {
    "./main": "./src/main",
    "./CounterWidget": "./src/widgets/counter-widget",
  },
  devPort: 3004,

  // Deliberately left as the default "vanilla" - there is no stack: "angular".

  transformBuildTimeConfig: (config) => ({
    ...config,
    module: {
      ...config.module,
      rules: [
        // 1. Angular's compiler replaces swc for TypeScript. Right to left:
        //    @ngtools/webpack compiles, then the bridge adds the HMR boundary it needs
        //    to find. Without it an edit reloads the whole page - shell included.
        {
          test: /\.[cm]?tsx?$/,
          use: [angularHmrBridgeLoader, "@ngtools/webpack"],
        },
        // 2. Angular ships its packages in "partial" Ivy form. AngularWebpackPlugin only
        //    compiles *your* TypeScript, so without the linker those declarations survive
        //    into the bundle and Angular falls back to JIT - which fails, because AOT
        //    deliberately keeps @angular/compiler out.
        {
          test: /\.m?js$/,
          include: /node_modules/,
          use: {
            loader: "babel-loader",
            options: {
              compact: false,
              babelrc: false,
              configFile: false,
              plugins: [require.resolve("@angular/compiler-cli/linker/babel")],
            },
          },
        },
        // 3. A component's styleUrl, handed back to the compiler as a plain string. The
        //    platform's css rules end in style-loader, which exports nothing - a styleUrl
        //    would silently compile to no styles at all. templateUrl needs no rule: the
        //    plugin reads .html straight off disk.
        {
          test: /\.css$/,
          resourceQuery: NG_RESOURCE,
          use: [{ loader: "css-loader", options: { exportType: "string" } }],
        },
        // 4. Everything @canopus/build set up, narrowed so it stops matching component
        //    resources.
        ...(config.module?.rules ?? [])
          .filter((rule) => !isSwcRule(rule))
          .map((rule) => (!rule || rule === "..." ? rule : { ...rule, resourceQuery: { not: [NG_RESOURCE] } })),
      ],
    },
    plugins: [
      ...(config.plugins ?? []),
      new EntryDependencyFactoryPlugin(),
      // AOT: templates compile at build time, so @angular/compiler stays out of the bundle.
      new AngularWebpackPlugin({
        tsconfig: path.join(here, "tsconfig.json"),
        jitMode: false,
      }),
    ],
  }),
});

import { applet } from "@canopus/foundation";
import { configureAngularApplication } from "@canopus/angular";
import { lazyAngularMountable } from "@canopus/angular/lazy";

/**
 * @canopus/angular implements layout.DomMountable - the same framework-agnostic contract
 * the Svelte and vanilla examples use. One ApplicationRef per applet, created lazily on
 * first mount: every mountable in this applet shares a DI root, and applets never share
 * one with each other.
 */
class AngularWorkshopApplet extends applet.Applet {
  readonly #app = lazyAngularMountable(() => import("./app/app.component").then((m) => m.AppComponent), {
    priority: 10_000,
    fallback: (el) => {
      el.textContent = "loading…";
    },
  });

  async onLoad() {
    this.logger.info("onLoad");

    // Root-injector providers for this applet's ApplicationRef, shared by every
    // mountable in it. It must run before the first mount: the application is created
    // lazily and its providers are fixed from that point, so a later call throws rather
    // than silently doing nothing.
    configureAngularApplication([]);

    this.addToMountLocation("appbar-middle", this.#app);
  }

  async onUnload() {
    this.logger.info("onUnload");
  }
}

const angularWorkshopApplet = new AngularWorkshopApplet();

export default angularWorkshopApplet;

import { ChangeDetectionStrategy, Component, input, signal } from "@angular/core";

@Component({
  selector: "ws_you_ng-app",
  changeDetection: ChangeDetectionStrategy.OnPush,
  templateUrl: "./app.component.html",
  styleUrl: "./app.component.css",
})
export class AppComponent {
  // A signal input with a default: "appbar-middle" declares no props, so nothing is
  // bound here. A *required* input would break at a location like that.
  readonly label = input("ws_you_ng");

  protected readonly count = signal(0);

  protected increment(): void {
    this.count.update((n) => n + 1);
  }
}

<button type="button" class="greeting" (click)="increment()">{{ label() }} &middot; {{ count() }}</button>

import { applet } from "@canopus/foundation";
import { lazyAngularMountable } from "@canopus/angular/lazy";

/**
 * No configureAngularApplication call here: the whole applet shares one ApplicationRef,
 * and ./src/main configures its providers before anything mounts.
 */
class CounterWidget extends applet.Applet {
  readonly #counter = lazyAngularMountable(
    () => import("./components/counter.component").then((m) => m.CounterComponent),
    {
      priority: 10_000,
      fallback: (el) => {
        el.textContent = "loading…";
      },
    },
  );

  async onLoad() {
    this.provideMountable(this.#counter);
  }
}

const counterWidget = new CounterWidget();

export default counterWidget;