Installation

Install django_components into your environment:
```
pip install django_components
```
Load django_components into Django by adding it into INSTALLED_APPS in in your settings file:
```
INSTALLED_APPS = [
    ...,
    'django_components',
]
```

BASE_DIR setting is required. Ensure that it is defined:

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

Optional. Set COMPONENTS.dirs and/or COMPONENTS.app_dirs so django_components knows where to find component HTML, JS and CSS files:

If COMPONENTS.dirs is omitted, django-components will by default look for a top-level /components directory, {BASE_DIR}/components.
```
from django_components import ComponentsSettings

COMPONENTS = ComponentsSettings(
    dirs=[
        ...,
        Path(BASE_DIR) / "components",
    ],
)
```
In addition to COMPONENTS.dirs, django_components will also load components from app-level directories, such as my-app/components/. The directories within apps are configured with COMPONENTS.app_dirs, and the default is [app]/components.

Note

The input to COMPONENTS.dirs is the same as for STATICFILES_DIRS, and the paths must be full paths. See Django docs.

Next, modify TEMPLATES section of settings.py as follows:

Remove 'APP_DIRS': True,
- NOTE: Instead of APP_DIRS: True, we will use django.template.loaders.app_directories.Loader, which has the same effect.
Add loaders to OPTIONS list and set it to following value:

This allows Django to load component HTML files as Django templates.

TEMPLATES = [
    {
        ...,
        'OPTIONS': {
            'loaders':[(
                'django.template.loaders.cached.Loader', [
                    # Default Django loader
                    'django.template.loaders.filesystem.Loader',
                    # Including this is the same as APP_DIRS=True
                    'django.template.loaders.app_directories.Loader',
                    # Components loader
                    'django_components.template_loader.Loader',
                ]
            )],
        },
    },
]

Adding support for JS and CSS¤

If you want to use JS or CSS with components, you will need to:

Add "django_components.finders.ComponentsFileSystemFinder" to STATICFILES_FINDERS in your settings file.

This allows Django to serve component JS and CSS as static files.

STATICFILES_FINDERS = [
    # Default finders
    "django.contrib.staticfiles.finders.FileSystemFinder",
    "django.contrib.staticfiles.finders.AppDirectoriesFinder",
    # Django components
    "django_components.finders.ComponentsFileSystemFinder",
]

Add ComponentDependencyMiddleware to MIDDLEWARE setting.

The middleware searches the outgoing HTML for all components that were rendered to generate the HTML, and adds the JS and CSS associated with those components.
```
MIDDLEWARE = [
    ...
    "django_components.middleware.ComponentDependencyMiddleware",
]
```
Read more in Rendering JS/CSS dependencies.

Add django-component's URL paths to your urlpatterns:

from django.urls import include, path

urlpatterns = [
    ...
    path("", include("django_components.urls")),
]

Optional. If you want to change where the JS and CSS is rendered, use {% component_js_dependencies %} and {% component_css_dependencies %}.

By default, the JS <script> and CSS <link> tags are automatically inserted into the HTML (See JS and CSS output locations).
```
<!doctype html>
<html>
  <head>
    ...
    {% component_css_dependencies %}
  </head>
  <body>
    ...
    {% component_js_dependencies %}
  </body>
</html>
```
Optional. By default, components' JS and CSS files are cached in memory.

If you want to change the cache backend, set the COMPONENTS.cache setting.

Read more in Caching.

Optional¤

Builtin template tags¤

To avoid loading the app in each template using {% load component_tags %}, you can add the tag as a 'builtin' in settings.py

TEMPLATES = [
    {
        ...,
        'OPTIONS': {
            'builtins': [
                'django_components.templatetags.component_tags',
            ]
        },
    },
]

Now you're all set! Read on to find out how to build your first component.