Getting started

This guide will help you get up and running with the Nasjonalbiblioteket monorepo, covering structure, installation, development workflows, and conventions.

Last modified: October 25, 2021

link Requirements

PHP 8.2 (managed via Composer)
Node 20 (managed via npm)
Composer - For PHP dependencies
Local by Flywheel (recommended for local WordPress development)

link Monorepo Structure

link Packages (`packages/`)

WordPress code and shared frontend packages:

packages/wordpress/plugins/ - Custom WordPress plugins (e.g., nb-employee, nb-event, site-bibliotekutvikling)
packages/wordpress/themes/ - WordPress themes (e.g., nb, bibliotekutvikling, kompetansebanken)
packages/wordpress/mu-plugins/ - Must-use plugins loaded automatically
packages/wordpress/libraries/ - Shared PHP libraries
packages/wordpress/external-plugins/ - Third-party premium plugins (ACF Pro, Gravity Forms, FacetWP, Polylang Pro, etc.)
packages/styles/ - Shared CSS packages (css-reset, forms, custom-media)
packages/tools/ - Build tools and webpack configuration

link Sites (`sites/`)

Individual site deployments:

nb/ - Main nb.no WordPress site
bibliotekutvikling/ - bibliotekutvikling.no WordPress site
maken/ - Maken React app (Create React App) ⚠️ Currently inactive - build process broken since last design change
ngram/ - N-gram viewer React + TypeScript app
embed/ - Reusable embeddable React components
translate/ - Translation management site
tibi/ - Tibi WordPress site

link Documentation (`docs/`)

Developer documentation built with Eleventy:

getting-started.md - Setup and onboarding
git-workflow.md - Branch naming, rebase workflow, PR process
packages.md - Package documentation
release-process.md - Deployment and release guide

View built docs: npm run docs:dev

link Installation

For complete setup instructions, see INSTALLATION.md

Quick start:

git clone <repository-url>
composer install
npm install
npm run build

link Development Workflows

link Build & Watch

npm run dev              # Turborepo parallel watch mode for all packages
npm run build            # Production build all packages

link Individual Sites

npm run dev:ngram        # Start ngram dev server
cd sites/maken && npm start  # Start maken dev server

link Documentation

npm run docs:dev         # Serve docs with live reload
npm run docs:build       # Build static docs

link Linting & Code Quality

npm run lint             # Run all linters (JS, CSS, format check)
npm run lint-fix         # Auto-fix linting issues
composer lint            # PHP CodeSniffer
composer lint-fix        # PHPCBF auto-fix

link Package Management

The monorepo uses dual package managers:

link npm Workspaces

JavaScript/TypeScript packages defined in root package.json:

packages/*
packages/styles/*
packages/tools/*
packages/wordpress/plugins/*
packages/wordpress/themes/*

link Composer

PHP packages managed via Composer with symlink-based local packages.

link Adding a New Package

WordPress plugin/theme/mu-plugin:

Create folder in packages/wordpress/{plugins|themes|mu-plugins}/your-package
Add composer.json with type (wordpress-plugin, wordpress-theme, wordpress-muplugin)
Add to root composer.json under require: "nb/your-package": "@dev"
Run composer update from project root
If it has front-end assets, add package.json and update root package.json workspaces

Updating packages:

npm outdated - Identify packages to update
npm update <package> - Update specific package
npm update <package> -w <workspace> - Update in specific workspace

link Build System

WordPress packages: Built with wp-scripts (WordPress webpack wrapper)
React apps: Create React App with custom configurations
CSS: PostCSS pipeline with imports, nesting, custom media queries, autoprefixer
Orchestration: Turborepo for parallel task execution

link Deployment

All deployments are automated via GitHub Actions:

WordPress sites: Deploy to GitLab repos via .github/workflows/deploy-*-gitlab.yml
React apps: Build and deploy to GitLab (e.g., deploy-main-maken.yaml, deploy-main-ngram.yml)
Trigger: main branch pushes deploy to staging/production

link Conventions

link Code Style

PHP: Dekode Coding Standards (WordPress variant)
JavaScript/TypeScript: WordPress ESLint rules with Prettier
CSS: wp-scripts lint-style with PostCSS
Pre-commit hooks via Husky enforce formatting

link Translation

Norwegian locale (nb_NO) is primary:

POT files in languages/ directory
Generate: composer make-pot
Translation files: .po and .mo format

link Additional Resources

Installation guide: INSTALLATION.md
Git workflow: Git Workflow
AI coding guide: .github/copilot-instructions.md