Installing Nunjucks Components

The Nunjucks Components library provides downloadable packages for all sections and partials. Each package includes everything you need to use the component in your project.

What's included in each package:

• Component template (.njk file)
• Styles (.css file, if applicable)
• JavaScript (.js file, if applicable)
• Manifest file with metadata and dependencies
• Configuration examples (.yaml file)
• Comprehensive README with usage instructions
• Automated installation script

Components are designed to work seamlessly with Nunjucks-based static site generators like Metalsmith and Eleventy.

Required Configuration

Before installing any components, create a nunjucks-components.config.json file in your project root:

{
  "componentsBasePath": "lib/layouts/components",
  "sectionsDir": "sections",
  "partialsDir": "_partials"
}

This configuration file is required for installation. Edit the values to match your project's directory structure. The install scripts read this file to determine where to place component files.

Every component package includes an automated installation script that handles the setup for you.

Installing an Individual Component

After downloading a component package, navigate to your project root directory (where your package.json file is located), extract the package there, and run the install script:

# Navigate to your project root
cd /path/to/your/project

# Extract the package in the project root
unzip ~/Downloads/hero.zip

# Navigate into the extracted component directory
cd hero

# Run the installation script
./install.sh

Important: Always extract component packages in your project root directory. The install script needs to be run from within the extracted component folder, but it will copy files to the correct locations (lib/layouts/components/sections/ or lib/layouts/components/_partials/) in your project.

After installation completes successfully, you can safely delete the extracted component folder (e.g., hero/) and the downloaded ZIP file.

The installation script will:

1. Verify nunjucks-components.config.json exists in your project root
2. Read component paths from your configuration
3. Check for existing installations and compare versions
4. Validate that required dependencies are installed
5. Copy component files to the correct locations
6. Report any missing dependencies with download links

Example Installation Output

🔧 Installing hero v0.0.1...

Checking dependencies...
⚠ Warning: Missing required partials:
  • text
  • ctas
  • image

Download from: https://nunjucks-components.netlify.app/downloads/

Continue installation anyway? (y/n)

If you proceed, the component files will be installed even if dependencies are missing. You can download the required partials later.

Installing the Complete Bundle

The bundle includes a master installation script with two modes: full install and update-only.

Full Install (Default)

Install all components or update your existing subset:

# Navigate to your project root
cd /path/to/your/project

# Ensure nunjucks-components.config.json exists (required)
# Create it if you haven't already - see "Required Configuration" above

# Extract the bundle in the project root
unzip ~/Downloads/nunjucks-components.zip

# Run the master installation script from project root
./nunjucks-components/install-all.sh

Important: The install script requires nunjucks-components.config.json in your project root. Create this file before running the installation (see "Required Configuration" in the Getting Started section above).

If you already have components installed, the script will prompt you to choose:

• Install all components - Adds new components, updates existing ones (52 total)
• Update existing components only - Only updates components you already have (skips new ones)

Update-Only Mode

Only update components you're already using:

./nunjucks-components/install-all.sh --update-only
# or use the short form:
./nunjucks-components/install-all.sh -u

This mode is perfect for:

• Getting updates for the specific components you use
• Avoiding bloat from components you don't need
• Quick updates when new versions are released

The update-only mode detects installed components by checking for manifest.json files. Only components with matching names will be updated. For example, if you're using one of the starter projects, approximately 22 components will be detected and updated.

The install script automatically:

• Installs all partials first (resolving dependencies)
• Then installs all sections
• Reports which components were installed/updated and which were skipped
• Provides a summary of the installation

After installation completes, you can clean up:

# Remove the extracted bundle folder
rm -rf nunjucks-components

# Optionally remove the downloaded ZIP file
rm ~/Downloads/nunjucks-components.zip

Understanding and managing component dependencies ensures your components work correctly.

How Dependencies Work

Most section components depend on one or more partial components. For example, the hero section requires:

• textpartial - for headings and prose content
• ctaspartial - for call-to-action buttons
• imagepartial - for hero images
• commonspartial - for shared utilities

These dependencies are automatically detected by your component bundler plugin (metalsmith-bundled-components for Metalsmith, eleventy-plugin-components-bundler for Eleventy), which bundles only the CSS and JavaScript actually used on each page.

Checking Dependencies

Each component's manifest.json file lists its dependencies:

{
  "name": "hero",
  "requires": ["text", "ctas", "image", "commons"]
}

You can also check the README.md file included in each package for a complete list.

Installing Missing Dependencies

If you're missing required partials, the installation script will warn you and provide download links. You can:

1. Download individual partials from their reference pages
2. Use the complete bundle to get all partials at once
3. Continue without the dependency (component may not render correctly)

Version Compatibility

All components share the same version number as the main project. When downloading components, they'll work together seamlessly regardless of when you downloaded them.

However, the contentHash field in each manifest.json tracks actual changes to component files. This allows the install script to detect when a component has truly changed vs. just having a version bump.

Context Requirements

Some components need more than just partial dependencies—they need access to external data or site-wide information. Check each component's manifest.json for a context array:

{
  "name": "podcast",
  "context": ["data.podcasts"],
  "requires": ["ctas", "commons"]
}

Components with context requirements need those properties passed through the template render chain via sections-renderer.njk and render-section.njk. For example, the podcast component needs data.podcasts to access podcast configuration files.

For details on setting up context passing, seeWorking with Data in Nunjucks Components.

Common issues and solutions when installing components.

Component Not Rendering

Problem:Component doesn't appear on the page after installation.

Solutions:

• Verify all required dependencies are installed
• Check that file paths are correct in your project structure
• Ensure your build process completed without errors
• Review the component's manifest.json for missing files

Build Errors

Problem:Build fails after installing a component.

Solutions:

• Check for YAML syntax errors in your frontmatter
• Verify the component's sectionType matches the component name
• Ensure all required fields are provided in your configuration
• Review build output for specific error messages

Missing Styles or Scripts

Problem:Component appears but styling or interactivity is missing.

Solutions:

• Verify your component bundler plugin is configured
• Check that CSS/JS files exist in the component directory
• Ensure your build process includes PostCSS for CSS processing
• Clear your browser cache and rebuild

Version Conflicts

Problem:Install script reports version conflicts.

Solutions:

• Check the contentHash to see if files actually changed
• Review the component's README for breaking changes
• Consider downloading the complete bundle for consistency
• Backup your customizations before upgrading

Permission Errors

Problem:Install script fails with permission errors.

Solutions:

• Make the install script executable: chmod +x install.sh
• Run from your project root directory
• Ensure you have write permissions in the project directory

For additional help, visit theComponent Architectureguide or review the YAML to HTML documentation.