django-components/docs/overview/installation.md at ccf02fa316536eb7d991a2723676da4978b0cdf0

mirror of https://github.com/django-components/django-components.git synced 2025-07-07 17:34:59 +00:00

chore: util to manage URLs in the codebase (#1179 )

* chore: util to manage URLs in the codebase

* docs: mentiion validate_links and supported_versions in docs

* refactor: fix linter errors

2025-05-11 14:59:34 +02:00

5.3 KiB

Raw Blame History

Basic installation

Install django_components into your environment:
```
pip install django_components
```

Load django_components into Django by adding it into INSTALLED_APPS in your settings file:

# app/settings.py
INSTALLED_APPS = [
    ...,
    'django_components',
]

BASE_DIR setting is required. Ensure that it is defined:

# app/settings.py
from pathlib import Path

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

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',
                ]
            )],
        },
    },
]

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

Django components already prefixes all URLs with components/. So when you are adding the URLs to urlpatterns, you can use an empty string as the first argument:
```
from django.urls import include, path

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

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",
]

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 Default JS / CSS 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',
            ]
        },
    },
]

Component directories

django-components needs to know where to search for component HTML, JS and CSS files.

There are two ways to configure the component directories:

COMPONENTS.dirs sets global component directories.
COMPONENTS.app_dirs sets app-level component directories.

By default, django-components will look for a top-level /components directory, {BASE_DIR}/components, equivalent to:

from django_components import ComponentsSettings

COMPONENTS = ComponentsSettings(
    dirs=[
        ...,
        Path(BASE_DIR) / "components",
    ],
)

For app-level directories, the default is [app]/components, equivalent to:

from django_components import ComponentsSettings

COMPONENTS = ComponentsSettings(
    app_dirs=[
        ...,
        "components",
    ],
)

!!! note

The input to [`COMPONENTS.dirs`](../reference/settings.md#django_components.app_settings.ComponentsSettings.dirs)
is the same as for `STATICFILES_DIRS`, and the paths must be full paths.
[See Django docs](https://docs.djangoproject.com/en/5.2/ref/settings/#staticfiles-dirs).

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

5.3 KiB Raw Blame History