refactor: usage notes + tests for safer_staticfiles (#538)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

sampleproject/.gitignore

@@ -1,2 +1,3 @@
 .python-version
 *.sqlite3
+staticfiles

sampleproject/README.md

@@ -0,0 +1,66 @@
+# Sample Django project with django_components
+
+## Installation
+
+1. Prepare virtual environment:
+
+   ```sh
+   python -m venv .venv
+   source .venv/bin/activate
+   ```
+
+2. Install dependencies:
+
+   ```sh
+   pip install -r requirements.txt
+   ```
+
+## Development server
+
+```sh
+python manage.py runserver
+```
+
+The app will be available at http://localhost:8000/.
+
+### Serving static files
+
+Assuming that you're running the dev server with `DEBUG=True` setting, ALL
+static files (JS/CSS/HTML/PY) will be accessible under the `/static/` URL path.
+
+## Production server
+
+1. Prepare static files
+
+   ```sh
+   python manage.py collectstatic
+   ```
+
+2. Set `DEBUG = False` in [settings.py](./sampleproject/settings.py).
+
+3. Start server with gunicorn
+
+   ```sh
+   gunicorn sampleproject.wsgi:application
+   ```
+
+The app will be available at http://localhost:8000/.
+
+### Serving static files
+
+This project uses [WhiteNoise](https://whitenoise.readthedocs.io/en/stable/) to configure Django to serve static files
+even for production environment.
+
+Assuming that you're running the prod server with:
+
+1. `DEBUG = False` setting
+2. `"django_components.safer_staticfiles"` in the `INSTALLED_APPS`
+
+Then Django will server only JS and CSS files under the `/static/` URL path.
+
+You can verify that this is true by starting the prod server and then navigating to:
+
+- http://127.0.0.1:8000/static/calendar/calendar.js
+- http://127.0.0.1:8000/static/calendar/calendar.css
+- http://127.0.0.1:8000/static/calendar/calendar.html
+- http://127.0.0.1:8000/static/calendar/calendar.py

sampleproject/requirements.txt

@@ -1,2 +1,4 @@
 django
 django_components
+gunicorn
+whitenoise

sampleproject/sampleproject/settings.py

@@ -19,7 +19,7 @@ SECRET_KEY = os.environ.get("SECRET_KEY", secrets.token_hex(100))
 # SECURITY WARNING: don't run with debug turned on in production!
 DEBUG = True
 
-ALLOWED_HOSTS: List[str] = []
+ALLOWED_HOSTS: List[str] = ["127.0.0.1", "localhost"]
 
 
 INSTALLED_APPS = [
@@ -39,6 +39,7 @@ INSTALLED_APPS = [
 
 MIDDLEWARE = [
     "django.middleware.security.SecurityMiddleware",
+    "whitenoise.middleware.WhiteNoiseMiddleware",
     "django.contrib.sessions.middleware.SessionMiddleware",
     "django.middleware.common.CommonMiddleware",
     "django.middleware.csrf.CsrfViewMiddleware",