JavaScript Project Structure and Build Standards

REFERENCE MODE: This skill provides reference material. Load specific standards on-demand based on current task.

Overview

This skill provides comprehensive standards for JavaScript project setup, structure, dependencies, and Maven integration in CUI projects. It covers directory layouts, package.json configuration, semantic versioning strategies, security management, ES module configuration, and frontend-maven-plugin integration for reproducible builds.

Prerequisites

To effectively use this skill, you should have:

• Understanding of npm package management
• Knowledge of Maven build lifecycle
• Familiarity with project structure conventions
• Experience with Node.js development

Standards Documents

This skill includes the following standards documents:

• project-structure.md - Directory layouts, file naming conventions, package.json structure, git ignore requirements
• dependency-management.md - Semantic versioning, security management, dependency updates, conflict resolution, ES module configuration
• maven-integration.md - Frontend Maven Plugin configuration, Maven phase integration, SonarQube integration, build environment standards

What This Skill Provides

Project Structure Standards

• Directory Layouts: Standard Maven, Quarkus DevUI, NiFi extension, standalone project structures
• File Naming: Kebab-case conventions, framework-specific prefixes (qwc-, nf-)
• Package.json Configuration: Essential structure, required fields, npm scripts
• Configuration Files: Location and naming for ESLint, Prettier, Jest, etc.
• Git Ignore Requirements: Essential exclusions for Node.js and Maven artifacts

Dependency Management

• Semantic Versioning: Caret ranges vs exact versions, version update strategies
• Security Management: Vulnerability scanning, response timeframes, resolution strategies
• Deprecated Packages: Common replacements, handling deprecation warnings
• Dependency Conflicts: Peer dependency resolution, npm overrides
• ES Module Configuration: "type": "module" setup, configuration file syntax requirements
• Update Management: Regular update schedules, breaking change handling

Maven Integration

• Frontend Maven Plugin: Required plugin setup, configuration parameters
• Phase Integration: Mapping npm scripts to Maven lifecycle phases
• Node.js Management: Version management, installation directory strategies
• Script Integration: Required npm scripts, execution order
• SonarQube Integration: Coverage reporting, quality gate configuration
• Build Environment: Reproducible builds, CI/CD integration
• Project Adaptations: Configuration for different project types

When to Activate

This skill should be activated when:

1. Setting Up New Project: Creating new JavaScript project with Maven integration
2. Configuring Project Structure: Establishing directory layout and file organization
3. Managing Dependencies: Adding, updating, or resolving dependency issues
4. Security Issues: Addressing npm vulnerabilities or deprecated packages
5. Maven Integration: Configuring frontend-maven-plugin or build pipeline
6. Build Issues: Troubleshooting Maven/npm integration problems
7. Updating Node.js: Changing Node.js or npm versions
8. SonarQube Setup: Configuring JavaScript coverage analysis
9. Project Type Adaptation: Adapting structure for Quarkus, NiFi, or multi-module projects
10. Best Practice Review: Ensuring project follows CUI standards

Workflow

When this skill is activated:

1. Identify Project Requirement

• Determine if new project setup or modification to existing
• Identify specific concern (structure, dependencies, Maven, security)
• Check current project type (Maven, Quarkus DevUI, NiFi, standalone)

2. Apply Project Structure Standards

• Use project-structure.md for directory layout selection
• Choose appropriate structure for project type
• Configure package.json with required fields and scripts
• Set up configuration files (.prettierrc.js, eslint.config.js, etc.)
• Create .gitignore with essential exclusions

3. Configure Dependency Management

• Reference dependency-management.md for version strategies
• Set up security audit scripts
• Configure semantic versioning (caret ranges for dev, exact for critical)
• Enable ES module support ("type": "module")
• Plan update management schedule

4. Integrate with Maven Build

• Use maven-integration.md for frontend-maven-plugin setup
• Configure Node.js version (see standards/project-structure.md for exact version)
• Map npm scripts to Maven phases
• Set up environment variables (CI=true, NODE_ENV=test)
• Configure SonarQube integration for JavaScript coverage

5. Validate Configuration

• Run Maven build to verify integration works
• Check Node.js installation in target/
• Verify npm scripts execute in correct phases
• Test dependency installation without errors
• Validate SonarQube picks up JavaScript coverage

Tool Access

This skill provides access to project standards through:

• Read tool for accessing standards documents
• Standards documents use Markdown format for consistency
• All standards are self-contained within this skill
• Cross-references between standards use relative paths

Integration Notes

Related Skills

For comprehensive frontend development, this skill works with:

• cui-javascript-linting skill - ESLint, Prettier, and StyleLint configuration
• cui-javascript skill - Core JavaScript development standards
• cui-jsdoc skill - JSDoc documentation standards
• cui-javascript-unit-testing skill - Jest testing standards

Build Integration

Project standards integrate with:

• npm for package management and script execution
• Maven for build automation via frontend-maven-plugin
• Node.js LTS for runtime environment (see standards/project-structure.md for exact version)
• SonarQube for quality analysis and coverage reporting
• Git for version control with proper .gitignore setup

Project Types

Standards support multiple project structures:

• Standard Maven: src/main/resources/static/js/
• Quarkus DevUI: src/main/resources/dev-ui/
• NiFi Extension: src/main/webapp/js/
• Standalone: src/main/js/
• Multi-Module: Nested frontend module structures

Best Practices

When setting up JavaScript projects for CUI:

1. Follow project type conventions - Use appropriate directory structure for Maven/Quarkus/NiFi/Standalone
2. Use kebab-case naming - Consistent file naming across all JavaScript files
3. Configure "type": "module" - Enable ES module support in package.json
4. Commit package-lock.json - Ensure reproducible builds across environments
5. Never commit node_modules/ - Always gitignore dependencies
6. Use caret ranges for dev dependencies - Allow automatic updates within major version
7. Use exact versions for critical deps - Pin production dependencies with breaking change history
8. Implement all required npm scripts - lint, format, test, quality scripts
9. Integrate with Maven properly - Map scripts to correct lifecycle phases
10. Set up security auditing - Regular vulnerability scanning and response
11. Use Node.js LTS - Consistent version managed by frontend-maven-plugin (see standards/project-structure.md for exact version)
12. Configure SonarQube coverage - JavaScript code quality and coverage analysis
13. Handle deprecations promptly - Replace deprecated packages before they become critical
14. Document project-specific setup - Update README.md with structure and setup instructions

Common Issues and Solutions

Project Structure Issues

• Wrong directory layout: Verify project type and use correct structure pattern
• Files not found during build: Check package.json script paths match structure
• Tests failing to locate sources: Update Jest testMatch patterns for directory layout

Dependency Management Issues

• npm install failures: Clear cache, delete node_modules/, regenerate package-lock.json
• Peer dependency conflicts: Try npm overrides before using --legacy-peer-deps
• Security vulnerabilities: Run npm audit fix, update vulnerable packages
• Deprecated packages: Identify replacements and update package.json

Maven Integration Issues

• Node.js installation failures: Check internet connectivity, proxy settings, disk space
• npm scripts not found: Verify scripts exist in package.json
• Build phase ordering: Ensure validate → generate-resources → compile → test
• Test failures in CI: Set CI=true, use test:ci-strict script
• SonarQube not picking up coverage: Verify lcov.info path matches SonarQube property

Configuration Issues

• ES module errors: Set "type": "module" in package.json
• Configuration files not loading: Ensure .prettierrc.js, eslint.config.js use export default
• Inconsistent builds: Commit package-lock.json, use frontend-maven-plugin for Node.js

Quick Reference

For detailed configuration examples and complete reference, see the individual standards documents:

• package.json structure and npm scripts - See

  project-structure.md

  for complete examples
• Directory structures by project type - See

  project-structure.md

  for Maven, Quarkus, NiFi, and standalone layouts
• Maven frontend-maven-plugin configuration - See

  maven-integration.md

  for complete plugin setup
• Semantic versioning strategies - See

  dependency-management.md

  for caret ranges vs exact versions
• Security audit setup - See

  dependency-management.md

  for audit scripts and vulnerability handling
• Git ignore patterns - See

  project-structure.md

  for essential .gitignore configuration

Key Requirements Summary

• Node.js Version: See

  project-structure.md

  for version requirements (managed by frontend-maven-plugin)
• Package.json: Must include

  "type": "module"

  for ES module support
• Required npm scripts: lint, format, test, test:ci-strict, quality
• Maven Integration: Map npm scripts to validate/compile/test phases
• Security: Implement audit scripts and respond to vulnerabilities within 30 days
• Version Control: Always commit package-lock.json, never commit node_modules/

Workflows

Workflow: npm Build Execution and Parsing

For npm/npx build execution and output parsing, use the builder-npm-rules skill:

Skill: pm-dev-builder:builder-npm-rules

The builder-npm-rules skill provides:

• Execute npm Build workflow - Atomic build execution with log capture
• Parse npm Build Output workflow - Issue categorization and routing

When to use builder-npm-rules:

• Running npm/npx builds (test, lint, build, etc.)
• Parsing npm build output for errors and warnings
• Categorizing build issues for orchestrated fixing
• Workspace-targeted builds in monorepos

Example usage:

Skill: pm-dev-builder:builder-npm-rules
Workflow: Execute npm Build
Parameters:
  command: run test
  workspace: e-2-e-playwright
  output_mode: structured

See builder-npm-rules skill documentation for complete workflow details.

Scripts

Script:

pm-dev-frontend:cui-javascript-project

npm-output.py

parse

Script characteristics:

• Uses Python stdlib only (json, argparse, re, pathlib)
• Outputs JSON to stdout
• Exit code 0 for success, 1 for errors
• Supports

  --help

  flag