# Repository: coreui/coreui-free-bootstrap-admin-template
# Stars: 12215

## .cursorrules

# CoreUI Free Bootstrap Admin Template - AI Context

## Project Overview
This is a Bootstrap 5 admin dashboard template built with CoreUI components. It uses Pug templating, Sass for styles, and vanilla JavaScript for interactivity.

## Critical Rules

### Component Library
- **ALWAYS use CoreUI Bootstrap components**: https://coreui.io/bootstrap/docs/
- **NEVER use Tailwind CSS** - this project uses Bootstrap 5 and custom Sass
- Use CoreUI's CSS classes and JavaScript components from `@coreui/coreui` package
- Reference the official CoreUI docs for component syntax and options

### Technology Stack
- **HTML Generation**: Pug templates (NOT raw HTML)
- **Styling**: Sass/SCSS with Bootstrap 5 (NO Tailwind)
- **JavaScript**: Vanilla JS with ES6 modules (NO frameworks like React/Vue)
- **Build System**: npm scripts with Babel, PostCSS, and custom build scripts

## Code Conventions

### JavaScript
- **No semicolons** - enforced by ESLint
- **2-space indentation**
- **ES6 modules** with import/export
- **Strict mode** enabled
- Use `/* global VariableName */` for external libraries
- Follow XO ESLint config with Unicorn plugin rules

### File Structure
```
src/
├── js/          # JavaScript modules (keep small and focused)
├── scss/        # Sass stylesheets (imports Bootstrap and CoreUI)
├── pug/         # Pug templates (source of truth for HTML)
│   ├── _layout/     # Base layouts
│   ├── _partials/   # Reusable components
│   ├── _mixins/     # Pug mixins
│   └── views/       # Page templates
├── assets/      # Images, icons, static files
└── views/       # Compiled HTML (auto-generated, don't edit)
```

### Pug Templates
- Use `extends ../_layout/default.pug` for new pages
- Override blocks: `block content`, `block scripts`
- Use mixins from `_mixins/` for common patterns
- Follow existing naming conventions for consistency

### CSS/Sass
- Use Bootstrap utilities first before custom CSS
- Use CSS custom properties (CSS variables) for theming
- Use Bootstrap/CoreUI class naming conventions (e.g., `.sidebar`, `.header`, `.card-title`)
- Support dark mode via `[data-coreui-theme="dark"]`
- **Never use**: `border-radius`, `transition`, `calc()` directly (Stylelint enforced)

### Naming Conventions
- **Files**: kebab-case (e.g., `color-modes.js`, `_header.pug`)
- **CSS classes**: Bootstrap/CoreUI conventions (e.g., `.btn-primary`, `.card-header`)
- **JavaScript variables**: camelCase
- **Constants**: UPPER_SNAKE_CASE

## Development Workflow

### Adding New Pages
1. Create Pug template in `src/pug/views/`
2. Extend base layout: `extends ../_layout/default.pug`
3. Add page-specific styles in `src/scss/` if needed
4. Add page-specific JS in `src/js/` if needed
5. Run `npm start` to compile and preview

### Adding New Components
1. **First check CoreUI docs**: https://coreui.io/bootstrap/docs/
2. Use CoreUI component markup in Pug files
3. Import required CoreUI JS modules if needed
4. Style using CoreUI/Bootstrap classes, not custom CSS
5. Create Pug mixin in `src/pug/_mixins/` for reusable patterns

### Build Commands
- `npm start` - Development with live reload
- `npm run build` - Production build
- `npm run watch-css` - Watch Sass changes
- `npm run watch-js` - Watch JavaScript changes
- `npm run watch-pug` - Watch Pug changes

## Code Quality

### Linting
- **JavaScript**: ESLint with XO config (flat config format)
- **Styles**: Stylelint with Bootstrap config
- **Formatting**: Prettier for HTML output
- Run `npm run lint` before committing

### Comments and Documentation
- **JSDoc required** for all functions with parameters
- Explain "why", not "what"
- Document complex template logic in Pug files
- Add file-level comments explaining module purpose

### Git Commits
Follow semantic commit format:
- `feat:` - New feature
- `fix:` - Bug fix
- `docs:` - Documentation changes
- `style:` - Code style changes (formatting)
- `refactor:` - Code refactoring
- `test:` - Test additions/changes
- `chore:` - Build/tooling changes

## Common Patterns

### Chart Integration
```javascript
/* global Chart */
import { getStyle } from '@coreui/utils'

const chart = new Chart(ctx, {
  type: 'line',
  data: { /* ... */ },
  options: { /* ... */ }
})
```

### Theme Switching
```javascript
import { ColorModeStorageManager } from '@coreui/coreui/js/color-modes'

document.addEventListener('ColorSchemeChange', () => {
  // React to theme changes
})
```

### Pug Mixin Usage
```pug
include _mixins/breadcrumb
+breadcrumb(['Home', 'Components', 'Buttons'])
```

## AI Assistance Guidelines

### When AI Should
- Use CoreUI Bootstrap components from official docs
- Generate Pug templates, not raw HTML
- Follow existing patterns in the codebase
- Add JSDoc comments to new JavaScript functions
- Respect ESLint/Stylelint rules
- Suggest npm scripts for tasks

### When AI Should NOT
- Use Tailwind CSS classes
- Use React/Vue/Angular components
- Edit compiled files in `dist/` or `src/views/`
- Add unnecessary dependencies
- Break existing build pipeline
- Ignore linting errors

## External Dependencies

### Core Libraries
- `@coreui/coreui` - CoreUI component library
- `chart.js` - Charts and graphs
- `simplebar` - Custom scrollbars

### Build Tools
- `sass` - CSS preprocessor
- `@babel/core` - JavaScript transpiler
- `pug` - HTML templating
- `postcss` - CSS post-processing
- `browser-sync` - Live reload server

## Browser Support
Defined in `.browserslistrc`:
- Last 1 major version of modern browsers
- Chrome, Firefox, Edge, Safari
- iOS Safari, Chrome Android

## Resources
- CoreUI Docs: https://coreui.io/bootstrap/docs/
- Chart.js Docs: https://www.chartjs.org/
- Pug Docs: https://pugjs.org/

## Project Maintainer Notes
- License: MIT
- Version: 5.4.0
- Repository: https://github.com/coreui/coreui-free-bootstrap-admin-template


## README.md

# CoreUI Free Bootstrap Admin Template — Built for AI-Assisted Development [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social&logo=twitter)](https://twitter.com/intent/tweet?text=CoreUI%20-%20Free%20Bootstrap%204%20Admin%20Template%20&url=https://coreui.io&hashtags=bootstrap,admin,template,dashboard,panel,free,angular,react,vue)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![@coreui coreui](https://img.shields.io/badge/@coreui%20-coreui-lightgrey.svg?style=flat-square)](https://github.com/coreui/coreui)
[![npm package][npm-coreui-badge]][npm-coreui]
[![NPM downloads][npm-coreui-download]][npm-coreui]

[npm-coreui]: https://www.npmjs.com/package/@coreui/coreui
[npm-coreui-badge]: https://img.shields.io/npm/v/@coreui/coreui.png?style=flat-square
[npm-coreui-download]: https://img.shields.io/npm/dm/@coreui/coreui.svg?style=flat-square

[![Bootstrap Admin Template](https://assets.coreui.io/products/coreui-free-bootstrap-admin-template-light-dark.webp)](https://coreui.io/product/free-bootstrap-admin-template/)

CoreUI Bootstrap Admin Panel Template is not another blend of 3rd parties free components and libraries. It's **the only Open Source Bootstrap Admin Dashboard Template built on the enterprise-grade hand-crafted [UI Components Library](https://github.com/coreui/coreui)** created and backed by professionals.
**CoreUI Admin Template helps you build reliable web apps faster than before.** CoreUI offers 4 versions: [Angular](https://github.com/coreui/coreui-free-angular-admin-template), [Bootstrap](https://github.com/coreui/coreui-free-bootstrap-admin-template), [React.js](https://github.com/coreui/coreui-free-react-admin-template), and [Vue.js](https://github.com/coreui/coreui-free-vue-admin-template).

Curious why I decided to create CoreUI? Please read this article: [Jack of all trades, master of none. Why Bootstrap Admin Templates suck.](https://medium.com/@lukaszholeczek/jack-of-all-trades-master-of-none-5ea53ef8a1f#.7eqx1bcd8)

## Table of Contents

* [Frameworks](#frameworks)
* [CoreUI PRO](#coreui-pro)
* [CoreUI PRO Bootstrap Admin Templates](#coreui-pro-bootstrap-admin-templates)
* [Installation](#installation)
* [Usage](#usage)
* [What's included](#whats-included)
* [AI-Friendly Development](#ai-friendly-development)
* [Documentation](#documentation)
* [Components](#components)
* [Contributing](#contributing)
* [Versioning](#versioning)
* [Creators](#creators)
* [Community](#community)
* [Support CoreUI Development](#support-coreui-development)
* [Copyright and license](#copyright-and-license)

## Frameworks

CoreUI is built on top of Bootstrap 5 and supports popular frameworks.

* [CoreUI Free Angular Admin Template](https://github.com/coreui/coreui-free-angular-admin-template)
* [CoreUI Free Bootstrap Admin Template](https://github.com/coreui/coreui-free-bootstrap-admin-template)
* [CoreUI Free React.js Admin Template](https://github.com/coreui/coreui-free-react-admin-template)
* [CoreUI Free Vue.js Admin Template](https://github.com/coreui/coreui-free-vue-admin-template)

## CoreUI PRO

* 💪  [CoreUI PRO Angular Admin Template](https://coreui.io/product/angular-dashboard-template/)
* 💪  [CoreUI PRO Bootstrap Admin Template](https://coreui.io/product/bootstrap-dashboard-template/)
* 💪  [CoreUI PRO Next.js Admin Template](https://coreui.io/product/next-js-dashboard-template/)
* 💪  [CoreUI PRO React Admin Template](https://coreui.io/product/react-dashboard-template/)
* 💪  [CoreUI PRO Vue Admin Template](https://coreui.io/product/vue-dashboard-template/)


## CoreUI PRO Bootstrap Admin Templates

| Default Theme | Light Theme |
| --- | --- |
| [![CoreUI PRO Bootstrap Admin Template](https://coreui.io/images/templates/coreui_pro_default_light_dark.webp)](https://coreui.io/product/bootstrap-dashboard-template/?theme=default) | [![CoreUI PRO Bootstrap Admin Template](https://coreui.io/images/templates/coreui_pro_light_light_dark.webp)](https://coreui.io/product/bootstrap-dashboard-template/?theme=light)|

| Modern Theme | Bright Theme |
| --- | --- |
| [![CoreUI PRO Bootstrap Admin Template](https://coreui.io/images/templates/coreui_pro_default_v3_light_dark.webp)](https://coreui.io/product/bootstrap-dashboard-template/?theme=modern) | [![CoreUI PRO Bootstrap Admin Template](https://coreui.io/images/templates/coreui_pro_light_v3_light_dark.webp)](https://coreui.io/product/bootstrap-dashboard-template/?theme=bright)|

## CoreUI Icons (522 Free icons) - Premium designed free icon set with marks in SVG, Webfont and raster formats.

CoreUI Icons are beautifully crafted symbols for common actions and items. You can use them in your digital products for web or mobile app. Ready-to-use fonts and stylesheets that work with your favorite frameworks.

[![CoreUI Free Icons](https://coreui.io/images/icons_free_bg_set.png)](https://github.com/coreui/coreui-icons/)

[Download CoreUI Free Icons](https://github.com/coreui/coreui-icons/)

## Installation

### Clone repo

``` bash
# clone the repo
$ git clone https://github.com/coreui/coreui-free-bootstrap-admin-template.git my-project

# go into app's directory
$ cd my-project

# install app's dependencies
$ npm install
```

## Usage

``` bash
# serve with hot reload at localhost:3000.
$ npm start

# build for production with minification
$ npm run build
```

## What's included

Within the download you'll find the following directories and files, logically grouping common assets and providing both compiled and minified variations. You'll see something like this:

```
free-bootstrap-admin-template/
├── build/
├── src/
│   ├── assets/
│   │   ├── brand/
│   │   ├── favicon/
│   │   ├── icons/
│   │   ├── img/
│   ├── js/
│   ├── pug/
│   │   ├── _layout/
│   │   ├── _partial/
│   │   ├── base/
│   │   ├── buttons/
│   │   ├── icons/
│   │   ├── notifications/
│   │   ├── ...
│   │   ├── index.pug
│   │   └── ...
│   ├── scss/
│   ├── vendors/
│   └── views/
│       ├── base/
│       ├── buttons/
│       ├── css/
│       ├── icons/
│       ├── notifications/
│       ├── ...
│       ├── index.html
│       └── ...
└── package.json
```

## AI-Friendly Development

This template is optimized for AI-assisted development, making it easier to work with AI coding assistants like Cursor, Claude Code, and GitHub Copilot.

### What's Included

- **`.cursorrules`** - Comprehensive AI context file with project conventions, patterns, and guidelines
- **`ARCHITECTURE.md`** - Detailed technical documentation covering the project structure, build pipeline, and component organization
- **`DEVELOPMENT.md`** - Practical developer guide with examples and best practices
- **JSDoc Comments** - All JavaScript modules include detailed documentation with @param and @returns annotations

### Benefits

- 🤖 **Smart Code Generation** - AI understands your project uses CoreUI Bootstrap (not Tailwind CSS)
- 📚 **Better Context Awareness** - AI knows the project structure, conventions, and patterns
- ✨ **Consistent Code Style** - AI generates code following ESLint/Stylelint rules automatically
- 🚀 **Faster Development** - Less time explaining, more time building
- 💡 **Intelligent Suggestions** - AI provides relevant component examples from CoreUI documentation

### Quick Start with AI

Simply open the project in your AI-powered IDE (Cursor, VS Code with Copilot, etc.) and the AI will automatically understand:
- Project architecture and file organization
- CoreUI Bootstrap component usage
- Pug templating patterns
- Sass/SCSS styling conventions
- JavaScript module patterns

## Documentation

The documentation for the CoreUI Free Bootstrap Admin Template is hosted at our website [CoreUI](https://coreui.io/bootstrap/docs/templates/installation/)

## Components

CoreUI Bootstrap Admin Templates are built on top of CoreUI and CoreUI PRO UI components libraries, including all of these components.

- [Bootstrap Accordion](https://coreui.io/bootstrap/docs/components/accordion/)
- [Bootstrap Alert](https://coreui.io/bootstrap/docs/components/alert/)
- [Bootstrap Autocomplete](https://coreui.io/bootstrap/docs/forms/autocomplete/) **PRO**
- [Bootstrap Avatar](https://coreui.io/bootstrap/docs/components/avatar/)
- [Bootstrap Badge](https://coreui.io/bootstrap/docs/components/badge/)
- [Bootstrap Breadcrumb](https://coreui.io/bootstrap/docs/components/breadcrumb/)
- [Bootstrap Button](https://coreui.io/bootstrap/docs/components/button/)
- [Bootstrap Button Group](https://coreui.io/bootstrap/docs/components/button-group/)
- [Bootstrap Callout](https://coreui.io/bootstrap/docs/components/callout/)
- [Bootstrap Card](https://coreui.io/bootstrap/docs/components/card/)
- [Bootstrap Carousel](https://coreui.io/bootstrap/docs/components/carousel/)
- [Bootstrap Checkbox](https://coreui.io/bootstrap/docs/forms/checkbox/)
- [Bootstrap Close Button](https://coreui.io/bootstrap/docs/components/close-button/)
- [Bootstrap Calendar](https://coreui.io/bootstrap/docs/components/calendar/) **PRO**
- [Bootstrap Collapse](https://coreui.io/bootstrap/docs/components/collapse/)
- [Bootstrap Date Picker](https://coreui.io/bootstrap/docs/forms/date-picker/) **PRO**
- [Bootstrap Date Range Picker](https://coreui.io/bootstrap/docs/forms/date-range-picker/) **PRO**
- [Bootstrap Dropdown](https://coreui.io/bootstrap/docs/components/dropdown/)
- [Bootstrap Floating Labels](https://coreui.io/bootstrap/docs/forms/floating-labels/)
- [Bootstrap Footer](https://coreui.io/bootstrap/docs/components/footer/)
- [Bootstrap Header](https://coreui.io/bootstrap/docs/components/header/)
- [Bootstrap Image](https://coreui.io/bootstrap/docs/components/image/)
- [Bootstrap Input](https://coreui.io/bootstrap/docs/forms/input/)
- [Bootstrap Input Group](https://coreui.io/bootstrap/docs/forms/input-group/)
- [Bootstrap List Group](https://coreui.io/bootstrap/docs/components/list-group/)
- [Bootstrap Loading Button](https://coreui.io/bootstrap/docs/components/loading-button/) **PRO**
- [Bootstrap Modal](https://coreui.io/bootstrap/docs/components/modal/)
- [Bootstrap Multi Select](https://coreui.io/bootstrap/docs/forms/multi-select/) **PRO**
- [Bootstrap Navs & Tabs](https://coreui.io/bootstrap/docs/components/navs-tabs/)
- [Bootstrap Navbar](https://coreui.io/bootstrap/docs/components/navbar/)
- [Bootstrap Offcanvas](https://coreui.io/bootstrap/docs/components/offcanvas/)
- [Bootstrap Pagination](https://coreui.io/bootstrap/docs/components/pagination/)
- [Bootstrap Password Input](https://coreui.io/bootstrap/docs/forms/password-input/) **PRO**
- [Bootstrap Placeholder](https://coreui.io/bootstrap/docs/components/placeholder/)
- [Bootstrap Popover](https://coreui.io/bootstrap/docs/components/popover/)
- [Bootstrap Progress](https://coreui.io/bootstrap/docs/components/progress/)
- [Bootstrap Radio](https://coreui.io/bootstrap/docs/forms/radio/)
- [Bootstrap Range](https://coreui.io/bootstrap/docs/forms/range/)
- [Bootstrap Range Slider](https://coreui.io/bootstrap/docs/forms/range-slider/) **PRO**
- [Bootstrap Rating](https://coreui.io/bootstrap/docs/forms/rating/) **PRO**
- [Bootstrap Select](https://coreui.io/bootstrap/docs/forms/select/)
- [Bootstrap Sidebar](https://coreui.io/bootstrap/docs/components/sidebar/)
- [Bootstrap Spinner](https://coreui.io/bootstrap/docs/components/spinner/)
- [Bootstrap Stepper](https://coreui.io/bootstrap/docs/forms/stepper/) **PRO**
- [Bootstrap Switch](https://coreui.io/bootstrap/docs/forms/switch/)
- [Bootstrap Table](https://coreui.io/bootstrap/docs/components/table/)
- [Bootstrap Textarea](https://coreui.io/bootstrap/docs/forms/textarea/)
- [Bootstrap Time Picker](https://coreui.io/bootstrap/docs/forms/time-picker/) **PRO**
- [Bootstrap Toast](https://coreui.io/bootstrap/docs/components/toast/)
- [Bootstrap Tooltip](https://coreui.io/bootstrap/docs/components/tooltip/)

## Contributing

Please read through our [contributing guidelines](https://github.com/coreui/coreui-free-bootstrap-admin-template/blob/main/.github/CONTRIBUTING.md). Included are directions for opening issues, coding standards, and notes on development.

Editor preferences are available in the [editor config](https://github.com/coreui/coreui-free-bootstrap-admin-template/blob/main/.editorconfig) for easy use in common text editors. Read more and download plugins at <http://editorconfig.org>.

## Versioning

For transparency into our release cycle and in striving to maintain backward compatibility,CoreUI Free Admin Template is maintained under [the Semantic Versioning guidelines](http://semver.org/).

See [the Releases section of our project](https://github.com/coreui/coreui-free-bootstrap-admin-template/releases) for changelogs for each release version.

## Creators

**Łukasz Holeczek**

* <https://twitter.com/lukaszholeczek>
* <https://github.com/mrholek>

**Andrzej Kopański**

* <https://github.com/xidedix>

**CoreUI Team**

* <https://twitter.com/core_ui>
* <https://github.com/coreui>
* <https://github.com/orgs/coreui/people>

## Community

Get updates on CoreUI's development and chat with the project maintainers and community members.

- Follow [@core_ui on Twitter](https://twitter.com/core_ui).
- Read and subscribe to [CoreUI Blog](https://coreui.io/blog/).

## Support CoreUI Development

CoreUI is an MIT-licensed open source project and is completely free to use. However, the amount of effort needed to maintain and develop new features for the project is not sustainable without proper financial backing. You can support development by buying the [CoreUI PRO](https://coreui.io/pricing/?framework=bootstrap&src=github-coreui-free-bootstrap-admin-template) or by becoming a sponsor via [Open Collective](https://opencollective.com/coreui/).


## Copyright and license

copyright 2026 creativeLabs Łukasz Holeczek. Code released under [the MIT license](https://github.com/coreui/coreui-free-bootstrap-admin-template/blob/main/LICENSE).