Adding DJ Lint

Python & djlint Installation Guide for BigCommerce Stencil Theme Development

Overview

This guide will help you install Python and pip on Windows 11, then set up djlint for linting HTML templates in your BigCommerce Stencil theme development environment.

Prerequisites

• Windows 11 operating system
• Visual Studio Code installed
• BigCommerce Stencil CLI already configured
• Administrator access to your computer

Step 1: Install Python

1. Download the Python installer:

   • Visit the official Python website: https://www.python.org/downloads/windows/
   • Download the latest Python 3.x Windows installer (64-bit recommended)

2. Run the installer:

   • Right-click the downloaded file and select “Run as administrator”
   • Check the box that says “Add Python to PATH” (very important!)
   • Select “Install Now” for a standard installation
   • Wait for the installation to complete

3. Verify Python installation:

   • Open Command Prompt (search for “cmd” in the Start menu)
   • Type: python --version
   • You should see the Python version displayed (e.g., “Python 3.11.x”)

Step 2: Verify pip Installation

Pip comes bundled with Python, but let’s make sure it’s working:

1. Open Command Prompt (as administrator recommended)

2. Verify pip installation:

   • Type: pip --version
   • You should see the pip version displayed

3. Update pip (recommended):

   • Type: python -m pip install --upgrade pip
   • This ensures you have the latest version of pip

Step 3: Install djlint

1. Install djlint via pip:

   • Open Command Prompt (as administrator recommended)
   • Type: pip install -U djlint
   • Wait for the installation to complete

2. Verify djlint installation:

   • Type: djlint --version
   • You should see the djlint version displayed

Step 4: Configure VS Code for djlint

1. Install VS Code extensions:

   • Open VS Code
   • Go to Extensions view (Ctrl+Shift+X)
   • Search for and install “djlint” extension

2. Configure VS Code settings:

   • Open Settings (Ctrl+,)
   • Click on “Open Settings (JSON)” in the top right corner
   • Add or modify the following settings:

{
    "[handlebars]": {
        "editor.defaultFormatter": "monosans.djlint"
    },
    "[html]": {
        "editor.defaultFormatter": "monosans.djlint"
    },
    "djlint.enableLinting": true,
    "djlint.formatOnSave": true
}

Step 5: Configure djlint for Stencil Themes

1. Create a djlint configuration file in your Stencil theme root:

   • Create a new file named .djlintrc in your theme’s root directory
   • Add the following configuration:

   {
       "extension": "html,hbs",
       "format_attribute_template_tags": true,
       "ignore": "node_modules,assets/dist",
       "indent": 2,
       "max_line_length": 100,
       "preserve_blank_lines": true,
       "profile": "handlebars"
   }

2. Test djlint with your Stencil templates:

   • Open Command Prompt in your theme directory
   • Run: djlint templates --check
   • To format all templates: djlint templates --reformat

Step 6: Integrate with your Stencil Workflow

1. Add to package.json scripts:

   • Open your theme’s package.json
   • Add the following to the “scripts” section:

   "scripts": {
   // existing scripts...
   "lint:templates": "djlint templates --check",
   "format:templates": "djlint templates --reformat"
   }

2. Usage with npm:

   • Check templates: npm run lint:templates
   • Format templates: npm run format:templates

Troubleshooting

Python not found after installation

• Make sure you checked “Add Python to PATH” during installation
• If missed, uninstall Python and reinstall with this option checked
• Alternatively, manually add Python path to environment variables

Pip not working

• Try using python -m pip instead of just pip
• Ensure your Command Prompt has admin privileges

djlint not found

• Try reinstalling with: python -m pip install djlint
• Check if Python Scripts folder is in your PATH

Additional Resources

• djlint Documentation
• BigCommerce Stencil Documentation
• Python Documentation

Notes for Rhino Rails Development

• This setup integrates well with your existing Tailwind CSS workflow
• Consider using djlint’s --check option as part of your pre-commit process
• The handlebars profile in djlint is compatible with Stencil’s templating system
• Test thoroughly with your custom theme components before deploying