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.

Intended Audience

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 React.

Layer	Technology	Purpose
Server-side	Python (Flask)	Flask UI resource view classes responsible for connecting backend data/services with frontend templates & rendering templates
Server-side	Jinja / JinjaX	Templating for static content and SEO-friendly pages
Client-side	React	Interactive components, forms, and dynamic UI

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

Jinja/JinjaX for Record Detail Pages

Record detail pages 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.

React for Interactive UI Components

React is used wherever the user interacts dynamically with data or state, such as:

Search and filtering interfaces
Deposition forms and submission workflows
Dashboards and widgets
Interactive data visualizations

React in NRP repositories is not used for full page rendering (as with SPA apps), but rather for embedding interactive components & React apps within context of Jinja-rendered pages.

When to Use Which Technology

Use Case	Technology	Reasoning
Detail pages with static content	Jinja/JinjaX	Fast, SEO-friendly
Interactive elements	React	State, reactivity
Forms	React	Validation, dynamic fields
Charts / Dashboards	React	Interactive 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.

Semantic UI React (for React components): https://react.semantic-ui.com
Semantic UI (for LESS/CSS and static pages): https://semantic-ui.com

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 (React, Jinja, webpack configuration).
assets/ – Global site-wide UI assets, like LESS styles and Semantic UI theme customizations.
templates/ – Globally shared and 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 code 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
  - - - Deposit.jinja
        RecordDetail.jinja
        Search.jinja
        Sidebar.jinja
        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

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

React Integration

Introduction to React in Invenio Developing React components and apps Integrating React into templates

Asset Management

Managing assets and dependencies.

Webpack Configuration

Internationalization (i18n)

Translating Jinja templates and React components.

I18n translations

Testing and Debugging

Testing Jinja Templates Testing React Components Debugging Tools and Techniques