Modern Songbook App (Next.js)

A modern, responsive web application for browsing, reading, and exporting songs from a structured songbook collection. Built with Next.js (v15.3.1) for improved performance and SEO capabilities.

This project is based on the documentation found in the root directory, including:

• nextjs-songbook-prd.md (Product Requirements)
• nextjs-songbook-structure.md (Detailed Directory Structure)
• nextjs-songbook-roadmap.md (Development Roadmap)
• CHANGELOG.md (Project Changes)

Features

• Server-side rendering for improved performance and SEO
• Responsive design that works on desktop, tablet, and mobile devices
• Browse and search through song collection with instant results. Use the search bar on the main page or the dedicated /search page to find songs by title, lyrics, author, language, or tags.
• Search suggestions and autocomplete with keyboard navigation and accessibility features. The search input shows matching titles, authors, composers, languages, and years as you type, with suggestions prioritized by relevance. Suggestions can be enabled/disabled site-wide through the admin interface.
• Filter songs by metadata: Clickable links for lyrics author, composer, year, and language on song detail pages navigate to filtered search results. The /search page accepts query parameters (e.g., ?lyricsAuthor=..., ?composer=..., ?year=..., ?language=...).
• View song lyrics with advanced markdown support, sanitized HTML, and visible stanza spacing. Lyrics are rendered using remark, remark-breaks, remark-html, and sanitized with dompurify. Stanzas are visually separated using Tailwind's [&_p+p]:mt-8 utility for clear readability.
• Typography customization with collapsible controls for font size, line spacing, and print-optimized view. Settings persist across sessions via localStorage.
• Access sheet music, audio recordings, and video performances (when available, with reliable downloads on all browsers via secure API)
• Export songs as PDF or Markdown for offline use - Implemented with backend API and frontend UI
• PWA functionality for offline access with service workers - Basic setup implemented with runtime caching
• Directory-based song management with organized structure
• Admin interface for song and file management - Fully implemented with add/edit/delete capabilities
• TypeScript support for improved code quality and developer experience
• Internationalization support for multilingual songbooks - Partially implemented, needs review
• Embedded PDF viewer for sheet music (when available, with reliable downloads on all browsers via secure API)
  • View sheet music PDFs directly in the browser without downloading
  • Navigate between pages with pagination controls
  • Responsive design adapts to different screen sizes
  • PDF.js integration provides cross-browser compatibility
  • Proper render task lifecycle management prevents canvas rendering conflicts
  • Clean resource management with automatic cleanup
  • Download option remains available for offline use

Tech Stack

• Framework: Next.js (App Router - v15.3.1)
• Language: TypeScript
• Styling: TailwindCSS (using neutral color scale for grays)
• State Management: React Query (Server), React Context (Client) - Note: React Query/Context not yet implemented
• Content Parsing: gray-matter, remark, remark-html, remark-breaks
• Document Export: pdf-lib - Fully implemented for PDF export
• Sanitization: dompurify - Fully implemented for client and server-side HTML sanitization
• PWA: next-pwa - Basic setup implemented with runtime caching
• Testing: Jest, React Testing Library - Implemented for unit, component, and integration tests

Getting Started

Prerequisites

• Node.js (Version specified in .nvmrc or latest LTS recommended)
• npm (comes with Node.js)

Installation

1. Clone the repository:

   git clone <your-repository-url>
   cd liderbuch
   

2. Install dependencies:

   npm install
   

3. Set up environment variables: Copy the .env.example file to .env.local and adjust the values as needed.

   cp .env.example .env.local
   

   Key variables:

   • NEXT_PUBLIC_API_URL: URL for the API (defaults to /api route within the app).
   • NEXT_PUBLIC_SITE_URL: The public URL of the site.
   • NEXT_PUBLIC_APP_NAME: The name displayed in the header and page titles (defaults to "Liderbuch").
   • CONTENT_DIR: The directory where song content is stored (defaults to content).

Running the Development Server

Start the development server (with Turbopack):

npm run dev

Open http://localhost:3000 with your browser to see the result.

Available Scripts

• npm run dev: Starts the development server with Turbopack.
• npm run build: Builds the app for production.
• npm start: Starts the production server (requires npm run build first).
• npm run lint: Runs ESLint to check for code style issues.
• npm test: Runs Jest tests.
• npm run test:watch: Runs Jest tests in watch mode.
• npm run test:coverage: Runs Jest tests with coverage report.
• npm run type-check: Runs TypeScript compiler checks.

Testing

The project includes a comprehensive testing setup with Jest and React Testing Library. The tests are organized into three categories:

Unit Tests

Unit tests focus on testing individual functions and small components in isolation. They are located in the tests/unit directory and follow the same structure as the source code.

npm test -- tests/unit

Integration Tests

Integration tests verify that different parts of the application work together correctly. These tests can include testing React components with their children, or API endpoints. They are located in the tests/integration directory.

npm test -- tests/integration

End-to-End Tests

End-to-end tests simulate real user interactions with the application. These tests require setting up Playwright or Cypress (not included in the basic setup). Placeholder files are available in the tests/e2e directory.

Coverage Reports

To generate test coverage reports, run:

npm run test:coverage

This will create a coverage report in the coverage directory.

Project Structure Overview

The project follows standard Next.js conventions with the App Router.

├── src/                  # Application source code
│   ├── app/              # Next.js App Router (routes, layouts, pages, API)
│   ├── components/       # Reusable React components (UI, domain-specific)
│   ├── lib/              # Utility functions (API clients, content parsing, etc.)
│   ├── hooks/            # Custom React hooks
│   ├── types/            # TypeScript type definitions
│   ├── contexts/         # React contexts
│   └── styles/           # Global styles, CSS variables
├── public/               # Static assets (images, fonts)
├── content/              # Song content (markdown, media)
├── tests/                # Unit, integration, E2E tests
├── docs/                 # Project documentation (non-code)
├── scripts/              # Helper scripts
├── .env.example          # Environment variable template
├── next.config.ts        # Next.js configuration
├── tailwind.config.js    # TailwindCSS configuration
├── tsconfig.json         # TypeScript configuration
├── package.json          # Project dependencies and scripts
└── ...                   # Other config files (.gitignore, eslint, etc.)

For a detailed breakdown, see nextjs-songbook-structure.md.

Adding Songs

1. Create a new folder inside the content/ directory (use kebab-case for the folder name, e.g., amazing-grace).
2. Inside the new folder, create a lyrics.md file.
3. Add YAML frontmatter at the beginning of the file for metadata, enclosed by triple hyphens (---). Include at least title. Example:

   ---
   title: Amazing Grace
   lyricsAuthor: John Newton
   # composer: (add if known)
   year: 1779
   language: English
   tags: [Hymn, Classic]
   ---
   

4. Add the song lyrics below the frontmatter.
   • Lyrics will be displayed with modern typography and formatting preserved. To create stanza breaks, insert a blank line between stanzas and no blank lines within a stanza. Lines within a stanza will appear together, separated by line breaks, and stanzas will have extra visible spacing between them.
5. Optionally add sheets/, media/audio/, media/video/, src/ subdirectories with corresponding files (PDFs, MP3s, MP4s, source scores). These files will be accessible via the secure API route.

Deployment

Refer to the "Deploy on Vercel" section in the standard Next.js documentation or the nextjs-songbook-readme.md for deployment instructions using Vercel or Docker.

Further Documentation

• Product Requirements: nextjs-songbook-prd.md
• Roadmap: nextjs-songbook-roadmap.md
• Directory Structure: nextjs-songbook-structure.md
• Changelog: CHANGELOG.md

Planned Features

The following features are planned but not yet fully implemented (see PRD and Roadmap in /docs/):

• Advanced markdown rendering for lyrics (with sanitization) - Partially implemented, needs review
• Advanced search features - Basic search and filtering implemented, advanced features like highlighting and suggestions planned
• User accounts, favorites, and playlists
• AI-powered search and recommendations
• Full internationalization (i18n) support - Partially implemented, needs review
• Comprehensive test suite - Partially implemented with Jest and React Testing Library

Accessibility & Design

Accessibility (WCAG 2.1 AA), responsive design, and semantic HTML are core priorities. The design system uses TailwindCSS and aims for consistent, readable typography and color contrast.

Documentation

For detailed requirements, structure, and roadmap, see the /docs/ directory:

• nextjs-songbook-prd.md (Product Requirements)
• nextjs-songbook-structure.md (Directory Structure)
• nextjs-songbook-roadmap.md (Development Roadmap)
• nextjs-songbook-status.md (Project Status)

Project Status

The project is currently in active development with several core features implemented:

• Core infrastructure with Next.js 15.3.1
• Song browsing, search, and detail views
• Admin interface for song management (add/edit/delete)
• File management for song-related media
• Export functionality (PDF/MD)
• Basic PWA support
• Testing infrastructure with Jest and React Testing Library

Many advanced features are still planned. See /docs/nextjs-songbook-status.md for up-to-date progress.

Usage: Searching for Songs

• Main Page Search Bar: On the main page (/), use the search bar to instantly find songs by title, lyrics, author, language, or tags using a general text query (q). Results update as you type, and matches are highlighted for clarity.
• Metadata Filtering: On individual song pages (/songs/[slug]), click on metadata fields like Lyrics Author, Composer, Year, or Language. This will take you to the /search page, pre-filtered to show songs matching that specific metadata.
• Direct Search Page: Navigate to /search and use URL query parameters to filter results directly (e.g., /search?composer=Example%20Composer&year=1990). The search API combines all provided filters.

Admin Interface

Features

• Add new songs with metadata and lyrics via a modal dialog accessible from the /admin route.
• Import existing songs from markdown files with automatic metadata extraction and directory structure creation.
• Edit existing songs, including all metadata and lyrics, with a fully accessible modal dialog (focus trap, ESC to close, keyboard navigation).
• Delete songs with confirmation.
• Two-Factor Authentication (2FA) for enhanced security:
  • TOTP-based authentication (compatible with Google Authenticator, Authy, etc.)
  • Initial setup page with QR code for easy onboarding
  • Secure session management with HTTP-only cookies
  • Logout functionality with confirmation dialog
• Manage files (sheet music, audio, video) for each song:
  • Upload new files (stored locally in the /content directory).
  • Download, preview, or delete files directly from the admin UI. Download links use the download attribute for best compatibility and do not open in a new tab.
  • File lists show file size, type, and provide download/view links.
• Site Settings Management:
  • Enable/disable search suggestions across the site
  • Settings are persisted in a configuration file
  • Real-time updates without requiring application restart
• All modals (Add Song, Import Song, Edit Song) use React Portal for robust focus management and to prevent focus loss during editing.
• All file links are now served securely via /api/files/[...path] API route, not from /public.
• The admin interface is accessible, responsive, and follows best UX practices.

How to Use

1. Go to /admin while running the app locally or in a protected environment.
2. Use the "Add New Song" button to create a new song entry through a modal dialog.
3. Use the "Import Song" button to upload and import existing markdown files with song content.
4. Use the table to edit, delete, or manage files for any song.
5. When editing, a modal will open with all fields pre-filled and fully editable. Focus and keyboard navigation are robust.

Security Features

• Two-Factor Authentication: Enhanced security for the admin interface with TOTP-based 2FA. See docs/2FA-SETUP.md for setup instructions.
  • Secure cookie handling with dynamic HTTPS detection for proper cookie security configuration
  • Compatible with standard authenticator apps (Google Authenticator, Authy, etc.)
  • Session management with HTTP-only cookies and proper logout functionality
  • Cross-device compatibility ensuring authentication works on desktop and mobile browsers
• Production-Ready File Serving: Files in /content are served via a secure API route (/api/files/[...path]).