frontend-app-aspects

Purpose

frontend-app-aspects is the frontend application for the Tutor Aspects plugin. It is built on frontend-base and ships slot operations/components that are loaded by the Open edX frontend shell.

This repository is not a template anymore. It is the source of the Aspects frontend integration code.

What This App Provides

The app currently contributes an instructor dashboard route widget through frontend-base slots:

• Slot ID: org.openedx.frontend.slot.instructorDashboard.routes.v1
• Widget ID: org.openedx.frontend.widget.instructorDashboard.route.aspects
• Operation: APPEND
• Rendered component: ReportsDashboard

The ReportsDashboard widget fetches Superset dashboard configuration and embeds dashboards using @superset-ui/embedded-sdk.

Runtime/Backend Expectations

At runtime, the widget expects LMS endpoints used by src/widgets/ReportsDashboard/data/api.ts:

• GET {lmsBaseUrl}/aspects/superset_instructor_dashboard/{courseId}/ returns dashboard configuration.
• The configuration includes superset_guest_token_url used to fetch a guest token for embedded Superset views.

If these endpoints are unavailable, the widget shows a localized error state.

Prerequisites

• Node version from .nvmrc
• npm
• Tutor development environment (recommended)

For Tutor MFE setup guidance, see tutor-mfe documentation.

Getting Started

TODO: This is generic for now, but we need to add instructions for running this app in a local Tutor environment. and how to run it with the rest of the instructor dashboard given that this only has a slot for now

1. Clone this repository:

   git clone https://github.com/openedx/frontend-app-aspects.git

2. Install dependencies:

   cd frontend-app-aspects && npm install

3. Start local development server:

   npm run dev

By default, the dev script uses:

• PORT=8080
• PUBLIC_PATH=/aspects

If needed, adjust the dev script in package.json to match your Tutor routing setup.

Local Development Against frontend-base

To develop this app together with a local checkout of frontend-base, use npm workspaces and the existing package scripts:

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

When finished, unmount with:

sudo umount packages/frontend-base

Configuration

This app is not configured by build-time environment variables. getAppConfig resolves three sources, in order of increasing precedence: the app's bundled defaultConfig, the site's commonAppConfig, and the app's config. The first is the app author's, at build time; the other two are the operator's, the second applying to every app on the site and the third to this app alone.

This app reads none of them. It bundles no defaultConfig and exposes no operator-settable keys of its own. The only configuration it depends on is site-level: lmsBaseUrl, from which the widget calls the endpoints listed under Runtime/Backend Expectations.

Developing

Common scripts:

• npm run dev: Run the local dev server.
• npm run build: Build library output into dist/.
• npm run build:ci: Run a full app webpack traversal for CI validation.
• npm run test: Run Jest tests with coverage.
• npm run lint: Run lint checks.

Project Structure

Important paths in this repository:

• src/app.ts: app declaration consumed by site.config.*.tsx
• src/constants.ts: app and role identifiers
• src/index.ts: package exports
• src/slots.tsx: slot operations applied to the shell
• src/widgets/ReportsDashboard: instructor Aspects dashboard widget
• src/setupTest.js: global test setup (including browser API shims)

Internationalization

Please follow the frontend-base i18n howto for message extraction and translation workflows.

Getting Help

If you are having trouble:

• Open edX forums: https://discuss.openedx.org
• Slack: request an Open edX Slack invitation and join #wg-frontend
• Repository issues: https://github.com/openedx/frontend-app-aspects/issues

For broader community help options, see Getting Help.

Branches and Releases

This app is published to NPM by semantic-release, and its branches follow OEP-10 ADR 0002:

main

Unstable. Every merge publishes a prerelease on the alpha dist-tag. Breaking changes land here with no DEPR process and no warning, so it is not supported in production. All changes, including bug fixes, should target this branch first.

stable

Carries the newest stable major and owns the latest dist-tag. Changes arrive here as backports from main, and no breaking change lands after publication.

n.x and n.m.x

Maintenance branches for majors and minors that stable has moved past. Each owns the dist-tag matching its own name, so consumers select a maintained line by semver range, e.g. "1.x".

stable is cut, and 1.0.2 is the current stable release. Both .releaserc and the Release CI workflow know the whole layout, including the maintenance branch patterns, so a new line starts publishing as soon as it is pushed.

This repository is not branched or tagged for Open edX releases in its own right. It participates by published version instead, per OEP-10 ADR 0003.

License

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

Please see LICENSE for details.

Contributing

Contributions are welcome. Please read How To Contribute.

This project accepts bug fixes, security fixes, maintenance work, and feature work. For larger features, open an issue first to align with maintainers.

All changes, including bug fixes, should target main first; see Branches and Releases for how they reach stable and the maintenance lines.

The Open edX Code of Conduct

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

People

Maintainers and project metadata are tracked in Backstage from catalog-info.yaml in this repository.

See Backstage.

Reporting Security Issues

Do not report security issues publicly. Email security@openedx.org instead.