Edifice TS Client

Edifice TS Client exposes frameworks for interacting with entcore-based servers APIs. It is written in typescript, with minimal dependencies (rxjs and axios at the moment).

Prerequisites

• pnpm: >= 7 | 8
• node: >= 16 | 18

Getting Started

pnpm install

Build

pnpm run build

Documentation

As rule of thumb, edifice-ts-client never uses any browser-related technology (no HTMLElement, Document, navigator...). It focus exclusively on data exchange with the servers.

• IConfigurationFramework is composed of 3 layers

  • Platform (apps, theme, analytics, i18n...)
  • School
  • User (preferences)

• ISession of the connected user

  • user
  • description
  • currentLanguage
  • notLoggedIn
  • avatarUrl
  • currentApp (the one which initialized the framework)
  • hasWorkflow
  • hasRight

• INotifyFramework for async messages

  • onLangReady
  • onSessionReady
  • onSkinReady
  • onOverridesReady
  • promisify (generic for creating/resolving/rejecting a Promise)
  • events (a publish/subscribe event broker)

• ITransportFramework wraps the HTTP protocol

• IExplorerFramework to look for resources

• IWidgetFramework dedicated to widgets conf/prefs

• and specific app frameworks for modeling their data

  • ITimelineApp
  • ...

Browse the full API documentation here

Additional developers notes

4 additional libs are installed by the pnpm install command.

• ViteJS as a Bundler
• Typedoc to generate the markdown documentation, in /docs, from the Typescript comments in source code.
• husky to install a local git pre-commit hook, in order to run the unit-tests and update /docs before every commit. => /docs will always be up-to-date on the git server.

The pnpm run build command will populate the /dist directory

• /dist/ts contains the JS code and associated .d.ts and .js.map files, later packaged in NPM (done by our CI).
• /dist/bundle contains the production-ready code/map.

So, you'll just have to write nice documented code, and unit tests where needed !

Push Force

git push --force is not recommended!

After a git history rewrite due to a git push --force, the git tags and notes referencing the commits that were rewritten are lost.

If it happens, read this troubleshooting section: Troubleshooting