Hummingbird

Hummingbird Theme for PrestaShop

Hummingbird is a modern, in-development theme for PrestaShop built to be compatible with versions <code>9.1.x</code> and above.

🔍 Theme Previews

| <img src="docs/thumb-homepage.png"> | <img src="docs/thumb-category.png"> | <img src="docs/thumb-product.png"> | | --- | --- | --- | | Homepage | Category | Product |

⚠️ Requirements

To work on Hummingbird, you'll need:

• Node.js v20.x.
• npm v8.

📑 Table of Contents

• Want to help develop the theme? Start with 🔨 Develop on Hummingbird.
• Want to preview or test it? Jump to 🐳 Run Hummingbird with Docker.
• Having issues with caching during development? Jump to 🥵 Troubleshooting.

🔨 Develop on Hummingbird

🧰 Installation / Setup

👀 Watch Mode Setup

From the project root run the following commands if you want to:

1. Install dependencies: <code>npm ci</code>. 2. Run watch mode to build assets: <code>npm run watch</code>. 3. You can now go to 🐳 Run Hummingbird with Docker section to run PrestaShop embedding Hummingbird.

🔥 Hot Module Reload (HMR) Setup

1. From the project root run: <code>npm ci</code>. 2. Navigate to the <code>webpack/</code> directory. 3. Run <code>cp .env-docker-example .env</code> or <code>cp .env-vhost-example .env</code> (depending on how you want to run your PrestaShop environment). 4. Edit <code>.env</code> with your local environment settings and ensure you use a free TCP port. 5. From the project root run <code>npm run dev</code>. 6. You can now go to 🐳 Run Hummingbird with Docker section to run PrestaShop embedding Hummingbird.

🖌️ Code Quality

To ensure code quality and consistency, run the following commands from the project root:

• Lint & auto-fix SCSS files: <code>npm run stylelint</code> or <code>npm run stylelint:fix</code>.
• Format & auto-format SCSS with Prettier: <code>npm run prettier</code> or <code>npm run prettier:fix</code>.
• Lint & auto-fix JS/TS files: <code>npm run lint</code> or <code>npm run lint:fix</code>.

🐳 Run Hummingbird with Docker

This theme includes Docker configurations for both PrestaShop and PrestaShop Flashlight development environments.

🛠️ Getting Started

Note: If you've already set up your development environment using <code>Watch Mode</code> or <code>Hot Module Reload (HMR)</code>, you can skip ahead to step 3.

1. From the project root run: <code>npm ci</code>. 2. Then run: <code>npm run build</code>. 3. Navigate to the <code>docker/</code> directory: <code>cd docker</code>. 4. Copy the example environment file: <code>cp .env-example .env</code>. 5. Edit <code>.env</code> to configure the following variables:

• <code>PS_TAG</code>: PrestaShop or Flashlight version tag.
• PrestaShop tags.
• Flashlight tags.
• <code>PLATFORM</code>: Platform architecture (e.g., linux/amd64, linux/arm64).
• <code>ADMIN_EMAIL</code>: Back office admin email.
• <code>ADMIN_PASSWORD</code>: Back office admin password.

📦 Available Configurations

• <code>docker-compose-prestashop.yml</code>: for standard PrestaShop development environment.
• <code>docker-compose-flashlight.yml</code>: for PrestaShop Flashlight development environment.

▶️ Starting the Environment

From the project root, run one of the following commands:

# For PrestaShop environment

docker compose -f docker/docker-compose-prestashop.yml up -d

For Flashlight environment

docker compose -f docker/docker-compose-flashlight.yml up -d

👀 After Starting the Environment

• PrestaShop/Flashlight will be available at http://localhost:8887 and BO at http://localhost:8887/admin-dev.
• phpMyAdmin will be available at http://localhost:8889.

⏹️ Stopping the Environment

From the project root, run one of the following commands:

# For PrestaShop environment

docker compose -f docker/docker-compose-prestashop.yml down -v

For Flashlight environment

docker compose -f docker/docker-compose-flashlight.yml down

🥵 Troubleshooting

> [!WARNING] > If you're experiencing issues with styles or assets not updating while using HMR mode, follow these steps to avoid browser and PrestaShop caching problems:

1. Disable browser cache during development:

• Open your browser's DevTools.
• Go to the <code>Network</code> tab.
• Enable <code>Disable cache</code> (⚠️ this only works while DevTools stays open).

2. Disable PrestaShop caching:

• In the back office, go to: <code>Advanced Parameters</code> → <code>Performance</code>.
• Under the Smarty section:
• Set Force compilation to <code>Yes</code>.
• Set Cache to <code>No</code>.
• Under the CCC (Combine, Compress and Cache) section:
• Disable all options.

📚 Storybook

Storybook is used to document and preview the theme's UI components during development. You can view the live documentation here. Since the theme is still in progress, contributions to improve or expand the documentation are welcome and encouraged.

▶️ Run Storybook Locally

To run Storybook on your machine:

1. Make sure project dependencies are installed, if not, from the project root run: <code>npm ci</code>. 2. Then run: <code>npm run storybook</code>. 3. Storybook will be available at http://localhost:6006.

🤝 Contributing

Please refer to the contributing guide.

✅ Continuous Integration

The CI runs include Stylelint, Prettier, ESLint, and TypeScript type checks.

🚀 Continuous Deployment

Whenever the <code>develop</code> branch is merged into <code>master</code>, the Storybook documentation is automatically deployed to GitHub Pages and becomes publicly accessible within minutes.

📄 License

This theme is released under the [Academic Free License 3.0][AFL-3.0].

[AFL-3.0]: https://opensource.org/licenses/AFL-3.0