Skip to Content
CustomizeRepository UIOverview

Front-end Development of NRP Repositories

The following guide provides a comprehensive overview of front-end development for NRP (National Repository Platform) repositories. It explains how to build, customize, and maintain the user interface components of NRP-based repository applications.

This guide is designed for:

  • Developers implementing UI features for their NRP repository instance.
  • Core NRP developers and contributors maintaining shared front-end components.

Frontend Architecture Overview

NRP repositories follow a hybrid architecture combining server-side rendering with Jinja/JinjaX templates and client-side interactivity via JavaScript (vanilla JS or React).

This design provides both fast initial page loads (thanks to server-side rendering) and rich interactivity (via JavaScript).

UI Modules as Python Packages

Unlike typical front-end development where everything is an NPM package, in NRP/InvenioRDM repositories UI elements are mostly shipped in Python packages or modules, providing both Jinja templates and webpack assets.

UI for NRP InvenioRDM repositories is packaged as Python packages or modules (except for some exceptions like react-searchkit and react-deposit-forms which are pure NPM packages). Each UI module contains:

  • Server-side assets: Jinja/JinjaX templates, Flask resource view classes
  • Client-side assets: JavaScript/React components, CSS/SCSS styles, static assets (images, fonts, etc.)
  • Webpack configuration: Python files (webpack.py) that declare webpack entry points, aliases, and NPM dependencies

This hybrid approach allows:

  • Integration between server-side rendering (templates) and client-side interactivity (JavaScript)
  • Single distribution for both frontend and backend components of a feature
  • Version coupling between Python backend and JavaScript frontend code

When adding UI features, you typically work within a Python package structure, not a standalone NPM package.

Jinja/JinjaX for Page Rendering

All pages in the repository are rendered using Jinja templates or JinjaX React-like components. These:

  • Are processed on the server side.
  • Receive data directly from backend UI resource view classes.
  • Produce pre-rendered HTML for fast loading and SEO benefits.

More dynamic pages (like search UI and deposit forms) also embed React apps and/or pure JavaScript for enhanced interactivity.

JavaScript for Interactive UI Components

Client-side JavaScript handles interactive elements. Choose based on complexity:

  • Vanilla JavaScript - For simple interactions like toggles, form hints, event listeners
  • React - For stateful interfaces like search, forms, dashboards

JavaScript in NRP repositories is not used for full page rendering (as with SPA apps), but rather for adding interactivity to Jinja-rendered pages.

When to Use Which Technology

Use CaseTechnologyReasoning
Detail pages with static contentJinja/JinjaXFast, SEO-friendly
Simple toggles, menus, form hintsVanilla JSLightweight, no build step
Complex search and filtering interfacesReactState, reactivity
FormsReactValidation, dynamic fields
Charts / DashboardsReactInteractive data-driven UI

Design System

NRP repositories use the Semantic UI design system, which ensures visual consistency between NRP-specific and Invenio-provided components.

While other design systems can be used, maintaining consistent look and feel across the application will require significant customization effort. Also dependency management may become much more complex, to avoid conflicts.

Repository Directory Structure

Each NRP repository typically has a structure like this:

          • ...

          Key folders

          • ui/ – All front-end related module-scoped code - typically for record models or shared components (React, Jinja, webpack configuration).
          • assets/ – Global site-wide UI assets, like LESS styles, Semantic UI theme customizations, fonts, graphics.
          • templates/ – Site-wide Jinja templates, overrides of built-in Invenio templates.
          • ui/components/ – Shared components used across multiple record models or other UI modules.
          • ui/mymodel/ – Front-end specific to the mymodel record model.

          Record Model UI Directory Structure

          Example structure for one specific record model (e.g., mymodel):

                      • index.js
                      • FormActionsContainer.jsx
                      • FormFieldsContainer.jsx
                      • index.js
                      • ResultsGridItem.jsx
                      • ResultsListItem.jsx
                      • banners.html
                      • main.html
              • __init__.py
              • webpack.py

          Key files & folders

          • webpack.py – Webpack configuration for this record model’s front-end assets. Declares new JS entry points, aliases, and NPM dependencies in Python. This is how each module contributes its UI assets to the shared resulting build.
          • __init__.py – Python module initializing the record model’s front-end UI package. Implements & registers UI resource view classes for server-side rendering.
          • templates/semantic-ui/mymodel/ – Jinja templates & JinjaX components specific to this record model (record detail, search page, deposit form). For interactive pages like search & deposit, these templates typically serve as mountpoints for React apps.
          • semantic-ui/js/mymodel/ – React components & apps specific to this record model (search results, deposit forms, etc).
          • semantic-ui/less/mymodel/ – LESS styles applicable to this record model components & templates.

          What’s Next?

          The following sections will guide you through specific front-end development topics regarding NRP repositories UI customization.

          Getting Started

          Set up your environment for front-end developmentPrerequisites

          Run the repository in development mode with live asset rebuilding

          Run development server

          Branding and Theming

          Introduction to Semantic UI theming system.

          Theming

          How to write, organize & override built-in LESS styles.

          Styling with LESS

          Customize color palette of the repository.

          Colors

          Customize fonts and typography styles.

          Typography

          Customize static text strings in templates and components.

          Copywriting

          How to provide image assets like logos and icons to be used in the UI.

          Image assets

          UI Resource Views

          UI Resource classes in Python connect backend service-level data to frontend templates.

          How to use and configure UI resource view classes.

          Resource views

          Templating

          Understanding how templates are collected, Jinja vs JinjaX, and page composition patterns.

          Overview: Jinja & JinjaX

          Jinja Templating

          How to create and customize Jinja templates for server-side UI rendering.

          Template inheritance, blocks, filters, and macros.

          Working with Jinja templates

          JinjaX Components

          How to create reusable JinjaX React-like components for use within Jinja templates.

          Reusable component patterns for Jinja templates.

          Creating and using JinjaX components

          JavaScript Assets

          Choosing between vanilla JS and React for interactivity

          JavaScript Assets Overview

          Vanilla JS for lightweight interactions

          Simple JavaScript

          React for complex, stateful UI components

          React

          Asset Management

          Managing entry points, aliases, and NPM dependencies.

          Webpack Configuration

          Internationalization (i18n)

          Translating Jinja templates and React components.

          I18n translations

          Testing and Debugging

          Testing Jinja TemplatesTesting React ComponentsDebugging Tools and Techniques

          References

          Last updated on
          ReferenceTheme