frontend-template-application

Purpose

This repository is a template for Open edX frontend applications built on frontend-base: a library that plugs into the Open edX frontend shell, rather than a standalone micro-frontend bundled with its own webpack build. It is flagged as a Template Repository, meaning it can be used as a basis for new GitHub repositories by clicking the green "Use this template" button above. The rest of this document describes how to work with your new frontend application after you've created a new repository from the template.

The legacy standalone MFE template (pre-frontend-base) lives on the legacy-mfe branch.

Getting Started

After copying the template repository, you'll want to do a find-and-replace to replace all instances of frontend-template-application with the name of your new repository. You should also pick a new appId and role name in src/constants.ts, and a friendly title in public/index.html.

Prerequisites

Tutor is currently recommended as the development environment for your new app. You can refer to the relevant tutor-mfe documentation to get started using it.

Cloning and Startup

In the following steps, replace "[PLACEHOLDER]" with the name of the repo you created when copying this template above.

1. Clone your new repo:

   git clone https://github.com/openedx/frontend-app-[PLACEHOLDER].git

2. Use the version of Node specified in the .nvmrc file.

   Using other major versions of Node may work, but is unsupported. This repository includes an .nvmrc file to help set the correct Node version via nvm.

3. Install npm dependencies:

   cd frontend-app-[PLACEHOLDER] && npm install

4. (Optional) Update the port and public path used for local development by editing the dev script in package.json. The default is PORT=8080 PUBLIC_PATH=/template.

5. Start the dev server:

   npm run dev

The dev server will be available at http://apps.local.openedx.io:8080 (or whatever port you configured), under the public path you configured.

Local Development Against frontend-base

To develop your app and a local checkout of frontend-base in tandem, use the built-in npm workspace support:

mkdir -p packages/frontend-base
sudo mount --bind /path/to/frontend-base packages/frontend-base
npm install
npm run dev:packages

Bind mounts are used instead of symlinks because Node resolves symlinks to their real paths, which breaks hoisted dependency resolution. When you are done, unmount with sudo umount packages/frontend-base.

Making Your New Project's README File

Move README-template-frontend-app.rst to your project's README.rst file. Please fill out all the sections - this helps other developers understand your app, how to install it, and how to use it.

Repository Setup

A repository created from a template inherits its files, but not its GitHub settings. Once your new repository exists, set up the following by hand:

1. Branch protection on main, requiring the Default CI and Lockfile Version check jobs. Leave room for a maintainer to push stable non-fast-forward, which is how a major graduates.
2. Secrets. CODECOV_TOKEN for coverage uploads, and publishing credentials for semantic-release. Both .releaserc and the Release CI workflow ship ready to use; the workflow publishes from any repository other than this template.
3. ``catalog-info.yaml``, so the component appears in Backstage with the right name, description, owner and links. See OEP-55.
4. A ``stable`` branch, cut from main when the app is first ready for production use. Until then main publishes alphas and there is nothing on the latest dist-tag. The branch layout is described in your new repository's README, and settled in OEP-10 ADR 0002.

Developing

This section concerns development of frontend-template-application itself, not the templated copy.

One of the goals of this repository is for it to function correctly as a frontend-base application (npm install && npm run dev) even if no modifications are made. This ensures that developers get a practical working example, not just a theoretical one.

This also means, of course, that any committed code should be tested and subject to both CI and branch protection rules.

The same goes for the release setup: .releaserc and the Release CI workflow are here so that copies get a working, OEP-10 ADR 0002-conformant one without editing anything. This repository is not itself published, so the workflow's job is gated on the repository name and never runs here. Keep both in sync with the ADR rather than with whatever any one app repository happens to be doing.

Project Structure

The layout follows the standard frontend-base app layout:

• src/app.ts - the app configuration imported by site.config.*.tsx
• src/constants.ts - the app's appId and role identifiers
• src/index.ts - the package's public exports (this is a library)
• src/routes.tsx - the app's react-router routes
• src/Main.tsx - the root component for the app's routes
• src/slots.tsx - the slot operations the app applies to the shell
• src/slots/ - the slots this app offers to consumers
• src/style.scss - app-scoped runtime styles

For more, see the frontend-base migration how-to.

Build Process Notes

Library build

npm run build compiles the library into dist/ via tsc and tsc-alias. This is what gets published and consumed by sites.

CI build

npm run build:ci runs openedx build against site.config.ci.tsx so webpack traverses the full app graph. This catches issues (like broken lazy-loaded imports) that tsc and Jest would not surface.

Internationalization

Please refer to the frontend-base i18n howto for documentation on internationalization.

Getting Help

If you're having trouble, we have discussion forums at https://discuss.openedx.org where you can connect with others in the community.

Our real-time conversations are on Slack. You can request a Slack invitation, then join our community Slack workspace. Because this is a frontend repository, the best place to discuss it would be in the #wg-frontend channel.

For anything non-trivial, the best path is to open an issue in this repository with as many details about the issue you are facing as you can provide.

https://github.com/openedx/frontend-template-application/issues

For more information about these options, see the Getting Help page.

License

The code in this repository is licensed under the AGPLv3 unless otherwise noted.

Please see LICENSE for details.

Contributing

Contributions are very welcome. Please read How To Contribute for details.

This project is currently accepting all types of contributions, bug fixes, security fixes, maintenance work, or new features. However, please make sure to have a discussion about your new feature idea with the maintainers prior to beginning development to maximize the chances of your change being accepted. You can start a conversation by creating a new issue on this repo summarizing your idea.

The Open edX Code of Conduct

All community members are expected to follow the Open edX Code of Conduct.

People

The assigned maintainers for this component and other project details may be found in Backstage. Backstage pulls this data from the catalog-info.yaml file in this repo.

Reporting Security Issues

Please do not report security issues in public, and email security@openedx.org instead.