Utility Scripts
Relevant source files
The following files were used as context for generating this wiki page:
The Umami repository contains a collection of Node.js scripts located in the scripts/ directory, designed to automate various development, build, and maintenance tasks. These scripts are orchestrated via npm or pnpm commands defined in the package.json file. They handle critical processes such as database management, internationalization (i18n) message compilation, and the application build process.
These utilities ensure a consistent development environment and streamline the deployment pipeline. They cover everything from initial database setup and seeding to compiling language files and checking environment configurations. Understanding these scripts is essential for developers contributing to the project or managing a self-hosted instance.
Script Overview
The package.json file defines a comprehensive set of scripts for managing the project lifecycle. These can be broadly categorized into build processes, database management, internationalization, and development utilities.
Sources: package.json:11-50
Key Scripts
| Command | Description |
|---|---|
pnpm run build | Executes the full build chain: checks environment, builds the database, verifies the DB, and builds the tracker and Next.js app. |
pnpm run build-lang | A meta-script that runs the full internationalization (i18n) pipeline. |
pnpm run check-db | Verifies the database connection, checks the version, and applies pending migrations. |
pnpm run seed-data | Populates the database with sample analytics data for two demo websites. |
pnpm run dev | Starts the Next.js development server with Turbo. |
pnpm run start | Starts the production Next.js server. |
Sources: package.json:12-50
Build Process
The main build process is initiated by pnpm run build. It uses npm-run-all to execute a sequence of scripts in order.
Sources: package.json:13
This diagram illustrates the sequence of tasks executed by the pnpm run build command.
Sources: package.json:13, package.json:28
Tracker Script Handling
The build process generates a script.js file, which is the analytics tracker. The next.config.ts file configures how this script is served. It allows for alternative tracker script names via the TRACKER_SCRIPT_NAME environment variable. Any specified names are added as rewrites to the main script.js.
Sources: next.config.ts:98-112
// next.config.ts:98-112
if (trackerScriptName) {
const names = trackerScriptName?.split(',').map(name => name.trim());
if (names) {
names.forEach(name => {
const normalizedSource = `/${name.replace(/^\/+/, '')}`;
rewrites.push({
source: normalizedSource,
destination: TRACKER_SCRIPT,
});
headers.push({
source: normalizedSource,
headers: trackerHeaders,
});
});
}
}
Database Management
Scripts in this category handle database initialization, validation, migration, and data seeding.
Database Check (check-db.js)
This script is a crucial part of the startup and build process. It performs several checks to ensure the database is ready. It can be skipped by setting the SKIP_DB_CHECK environment variable.
Sources: scripts/check-db.js:8-11, package.json:32
The following diagram shows the workflow of the check-db.js script.
Data Seeding (seed-data.ts)
For development and testing, the seed-data.ts script can be used to populate the database with realistic sample data. It is invoked via pnpm run seed-data.
The script is designed to be safe and will exit if it detects a production environment (NODE_ENV=production) or a cloud hosting environment (Vercel, Netlify, Railway).
Sources: scripts/seed-data.ts:1-15, scripts/seed-data.ts:90-100
Arguments
The script's behavior can be modified with command-line arguments.
| Argument | Description | Default |
|---|---|---|
--days <number> | Number of days of data to generate. | 30 |
--clear | Clear existing demo data before generating new data. | false |
--verbose or -v | Show detailed progress during generation. | false |
--help or -h | Show the help message. | N/A |
Sources: scripts/seed-data.ts:18-45, scripts/seed-data.ts:68-88
Internationalization (i18n)
The project uses a set of scripts to manage and compile language files for the UI. The main command pnpm run build-lang orchestrates this process.
Sources: package.json:25
The i18n workflow involves extracting messages from the source, merging them with existing translations, formatting them, and finally compiling them for production use.
This diagram shows the flow of message processing for internationalization.
Sources: package.json:25, package.json:35-39
merge-messages.js
This script takes the newly extracted messages from build/extracted-messages.json and merges them into the existing language files located in src/lang. If a key is missing from a language file, it is added with the default message (from English), and a log is printed to the console. For en-US.json, it always overwrites the value with the newly extracted default message.
Sources: scripts/merge-messages.js:1-20
format-lang.js
This script reads the simple key-value JSON files from src/lang and transforms them into the structure required by format-js, which includes a defaultMessage property for each key. The output is written to the build/messages directory.
Sources: scripts/format-lang.js:1-25
// scripts/format-lang.js:18-21
const formatted = keys.reduce((obj, key) => {
obj[key] = { defaultMessage: lang[key] };
return obj;
}, {});
Summary
The utility scripts in the Umami project are a foundational component of the development and deployment workflow. They provide robust automation for database management, build compilation, and internationalization, ensuring consistency and reducing manual effort. Developers should familiarize themselves with the scripts in package.json to effectively build, test, and maintain the application.