File-based routing

Instead of defining routes in your code...

File-based routing

Instead of defining routes in your code...

...routes are defined by your code.

File-based routing

Instead of defining routes in your code...

...routes are defined by your code structure.

pages/index.jsx       →  /
pages/blog/index.jsx  →  /blog

pages/index.jsx       →  /
pages/blog/index.jsx  →  /blog

How is this possible?

JavaScript exports

// pages/index.jsx
 
export default function HomePage() {
    return <h1>Hello, world!</h1>;
}
// pages/index.jsx
 
export default function HomePage() {
    return <h1>Hello, world!</h1>;
}

pages/
├── blog/
│   ├── index.jsx            →  /blog
│   └── [slug].jsx           →  /blog/:slug
├── profile/
│   └── [username]/
│       ├── index.jsx        →  /profile/:username
│       └── likes.jsx        →  /profile/:username/likes
├── settings/
│   └── account/
│       └── password.jsx     →  /settings/account/password
├── unknown/
│   └── [...all].jsx         →  /unknown/*
└── index.jsx                →  /

Why is it so popular?

code structure ↔️ url structure

Why is it so popular?

import BlogPost from 'pages/blog/[slug]';

File structure

pages/
├── about.jsx
├── index.jsx
├── posts/
│   ├── [slug].jsx
│   └── index.jsx
└── projects/
    ├── [id].jsx
    └── index.jsx

File structure

pages/
├── about.jsx
├── index.jsx
├── posts/
│   ├── [slug].jsx
│   └── index.jsx
└── projects/
    ├── [id].jsx
    └── index.jsx

myapp/views/
├── about.py
├── index.py
├── posts/
│   ├── [slug].py
│   └── index.py
└── projects/
    ├── [id].py
    └── index.py

File structure

pages/
├── about.jsx
├── index.jsx
├── posts/
│   ├── [slug].jsx
│   └── index.jsx
└── projects/
    ├── [id].jsx
    └── index.jsx

myapp/views/
├── about.py
├── __init__.py
├── posts/
│   ├── [slug].py
│   └── __init__.py
└── projects/
    ├── [id].py
    └── __init__.py

File structure

pages/
├── about.jsx
├── index.jsx
├── posts/
│   ├── [slug].jsx
│   └── index.jsx
└── projects/
    ├── [id].jsx
    └── index.jsx

myapp/views/
├── about.py
├── __init__.py
├── posts/
│   ├── <slug:slug>.py
│   └── __init__.py
└── projects/
    ├── <int:id>.py
    └── __init__.py

File structure

pages/
├── about.jsx
├── index.jsx
├── posts/
│   ├── [slug].jsx
│   └── index.jsx
└── projects/
    ├── [id].jsx
    └── index.jsx

myapp/views/
├── about.py
├── __init__.py
├── posts/
│   ├── __slug__slug__.py
│   └── __init__.py
└── projects/
    ├── __int__id__.py
    └── __init__.py

File structure

pages/
├── about.jsx
├── index.jsx
├── posts/
│   ├── [slug].jsx
│   └── index.jsx
└── projects/
    ├── [id].jsx
    └── index.jsx

myapp/views/
├── about.py
├── __init__.py
├── posts/
│   ├── slug.py
│   └── __init__.py
└── projects/
    ├── id.py
    └── __init__.py

Views

export default function HomePage() {
    return <h1>Hello, world!</h1>;
}

Views

export default function HomePage() {
    return <h1>Hello, world!</h1>;
}

def default(request):
    return HttpResponse("Hello, world!")

Views

export default function HomePage() {
    return <h1>Hello, world!</h1>;
}

def view(request):
    return HttpResponse("Hello, world!")

Views

export default function HomePage() {
    return <h1>Hello, world!</h1>;
}

def dispatch(request):
    return HttpResponse("Hello, world!")

Hooking it into urls.py

urlpatterns = [
    fs_paths("myapp.views"),
    # or fs_paths("myapp/views") ?
    # or *fs_paths("myapp/views") ?
]
urlpatterns = [
    fs_paths("myapp.views"),
    # or fs_paths("myapp/views") ?
    # or *fs_paths("myapp/views") ?
]

fs_paths

def fs_paths(module_path):
    ...

fs_paths

def fs_paths(module_path):
    # 1. Get the module object from module_path (dynamic import)

fs_paths

def fs_paths(module_path):
    # 1. Get the module object from module_path (dynamic import)
    # 2. Use getattr(module, "dispatch") to get the view function

fs_paths

def fs_paths(module_path):
    # 1. Get the module object from module_path (dynamic import)
    # 2. Use getattr(module, "dispatch") to get the view function
    # 3. Construct path(route, view)

fs_paths

def fs_paths(module_path):
    # 1. Get the module object from module_path (dynamic import)
    # 2. Use getattr(module, "dispatch") to get the view function
    # 3. Construct path(route, view)
    # 4. Repeat for all submodules
def fs_paths(module_path):
    # 1. Get the module object from module_path (dynamic import)
    # 2. Use getattr(module, "dispatch") to get the view function
    # 3. Construct path(route, view)
    # 4. Repeat for all submodules

fs_paths

from importlib import import_module
 
def fs_paths(module_path):
    module = import_module(module_path)
    # 2. Use getattr(module, "dispatch") to get the view function
    # 3. Construct path(route, view)
    # 4. Repeat for all submodules
from importlib import import_module
 
def fs_paths(module_path):
    module = import_module(module_path)
    # 2. Use getattr(module, "dispatch") to get the view function
    # 3. Construct path(route, view)
    # 4. Repeat for all submodules

fs_paths

from importlib import import_module
 
def fs_paths(module_path):
    module = import_module(module_path)
    view = getattr(module, "dispatch")
    # 3. Construct path(route, view)
    # 4. Repeat for all submodules
from importlib import import_module
 
def fs_paths(module_path):
    module = import_module(module_path)
    view = getattr(module, "dispatch")
    # 3. Construct path(route, view)
    # 4. Repeat for all submodules

fs_paths

from importlib import import_module
from django.urls import path
 
def fs_paths(module_path):
    module = import_module(module_path)
    view = getattr(module, "dispatch")
    return path("", view, name="index")
    # 4. Repeat for all submodules
from importlib import import_module
from django.urls import path
 
def fs_paths(module_path):
    module = import_module(module_path)
    view = getattr(module, "dispatch")
    return path("", view, name="index")
    # 4. Repeat for all submodules

fs_paths

from importlib import import_module
from django.urls import path
 
def fs_paths(module_path):
    result = []
    module = import_module(module_path)
    view = getattr(module, "dispatch", None)
    if callable(view):
        result.append(path("", view, name="index"))
 
    return path("", include((result, module_path)))
from importlib import import_module
from django.urls import path
 
def fs_paths(module_path):
    result = []
    module = import_module(module_path)
    view = getattr(module, "dispatch", None)
    if callable(view):
        result.append(path("", view, name="index"))
 
    return path("", include((result, module_path)))
from importlib import import_module
from django.urls import path
 
def fs_paths(module_path):
    result = []
    module = import_module(module_path)
    view = getattr(module, "dispatch", None)
    if callable(view):
        result.append(path("", view, name="index"))
 
    return path("", include((result, module_path)))

fs_paths

from importlib import import_module
from django.urls import path
 
def fs_paths(module_path, namespace=None):
    result = []
    module = import_module(module_path)
    view = getattr(module, "dispatch", None)
    if callable(view):
        result.append(path("", view, name="index"))
 
    if not namespace:
        namespace = module_path
    return path("", include((result, namespace)))

fs_paths

from pkgutil import walk_packages
from importlib import import_module
from django.urls import path
 
def fs_paths(module_path, namespace=None):
    result = []
    module = import_module(module_path)
    view = getattr(module, "dispatch", None)
    if callable(view):
        result.append(path("", view, name="index"))
 
    if not namespace:
        namespace = module_path
 
    prefix = f"{module_path}.")
    for pkg in walk_packages(module.__path__, prefix=prefix):
        finder, name, _ = pkg  # pkgutil.ModuleInfo
        module = finder.find_module(name).load_module(name)
        view = getattr(module, "dispatch", None)
        route_name = name[len(prefix):]
        route = route_name.replace('.', '/')
        if callable(view):
            result.append(path(route, view, name=route_name))
 
    result.sort(key=lambda x: str(x.pattern), reverse=True)
 
    return path("", include((result, namespace)))
from pkgutil import walk_packages
from importlib import import_module
from django.urls import path
 
def fs_paths(module_path, namespace=None):
    result = []
    module = import_module(module_path)
    view = getattr(module, "dispatch", None)
    if callable(view):
        result.append(path("", view, name="index"))
 
    if not namespace:
        namespace = module_path
 
    prefix = f"{module_path}.")
    for pkg in walk_packages(module.__path__, prefix=prefix):
        finder, name, _ = pkg  # pkgutil.ModuleInfo
        module = finder.find_module(name).load_module(name)
        view = getattr(module, "dispatch", None)
        route_name = name[len(prefix):]
        route = route_name.replace('.', '/')
        if callable(view):
            result.append(path(route, view, name=route_name))
 
    result.sort(key=lambda x: str(x.pattern), reverse=True)
 
    return path("", include((result, namespace)))
from pkgutil import walk_packages
from importlib import import_module
from django.urls import path
 
def fs_paths(module_path, namespace=None):
    result = []
    module = import_module(module_path)
    view = getattr(module, "dispatch", None)
    if callable(view):
        result.append(path("", view, name="index"))
 
    if not namespace:
        namespace = module_path
 
    prefix = f"{module_path}.")
    for pkg in walk_packages(module.__path__, prefix=prefix):
        finder, name, _ = pkg  # pkgutil.ModuleInfo
        module = finder.find_module(name).load_module(name)
        view = getattr(module, "dispatch", None)
        route_name = name[len(prefix):]
        route = route_name.replace('.', '/')
        if callable(view):
            result.append(path(route, view, name=route_name))
 
    result.sort(key=lambda x: str(x.pattern), reverse=True)
 
    return path("", include((result, namespace)))
from pkgutil import walk_packages
from importlib import import_module
from django.urls import path
 
def fs_paths(module_path, namespace=None):
    result = []
    module = import_module(module_path)
    view = getattr(module, "dispatch", None)
    if callable(view):
        result.append(path("", view, name="index"))
 
    if not namespace:
        namespace = module_path
 
    prefix = f"{module_path}.")
    for pkg in walk_packages(module.__path__, prefix=prefix):
        finder, name, _ = pkg  # pkgutil.ModuleInfo
        module = finder.find_module(name).load_module(name)
        view = getattr(module, "dispatch", None)
        route_name = name[len(prefix):]
        route = route_name.replace('.', '/')
        if callable(view):
            result.append(path(route, view, name=route_name))
 
    result.sort(key=lambda x: str(x.pattern), reverse=True)
 
    return path("", include((result, namespace)))
from pkgutil import walk_packages
from importlib import import_module
from django.urls import path
 
def fs_paths(module_path, namespace=None):
    result = []
    module = import_module(module_path)
    view = getattr(module, "dispatch", None)
    if callable(view):
        result.append(path("", view, name="index"))
 
    if not namespace:
        namespace = module_path
 
    prefix = f"{module_path}.")
    for pkg in walk_packages(module.__path__, prefix=prefix):
        finder, name, _ = pkg  # pkgutil.ModuleInfo
        module = finder.find_module(name).load_module(name)
        view = getattr(module, "dispatch", None)
        route_name = name[len(prefix):]
        route = route_name.replace('.', '/')
        if callable(view):
            result.append(path(route, view, name=route_name))
 
    result.sort(key=lambda x: str(x.pattern), reverse=True)
 
    return path("", include((result, namespace)))
from pkgutil import walk_packages
from importlib import import_module
from django.urls import path
 
def fs_paths(module_path, namespace=None):
    result = []
    module = import_module(module_path)
    view = getattr(module, "dispatch", None)
    if callable(view):
        result.append(path("", view, name="index"))
 
    if not namespace:
        namespace = module_path
 
    prefix = f"{module_path}.")
    for pkg in walk_packages(module.__path__, prefix=prefix):
        finder, name, _ = pkg  # pkgutil.ModuleInfo
        module = finder.find_module(name).load_module(name)
        view = getattr(module, "dispatch", None)
        route_name = name[len(prefix):]
        route = route_name.replace('.', '/')
        if callable(view):
            result.append(path(route, view, name=route_name))
 
    result.sort(key=lambda x: str(x.pattern), reverse=True)
 
    return path("", include((result, namespace)))
from pkgutil import walk_packages
from importlib import import_module
from django.urls import path
 
def fs_paths(module_path, namespace=None):
    result = []
    module = import_module(module_path)
    view = getattr(module, "dispatch", None)
    if callable(view):
        result.append(path("", view, name="index"))
 
    if not namespace:
        namespace = module_path
 
    prefix = f"{module_path}.")
    for pkg in walk_packages(module.__path__, prefix=prefix):
        finder, name, _ = pkg  # pkgutil.ModuleInfo
        module = finder.find_module(name).load_module(name)
        view = getattr(module, "dispatch", None)
        route_name = name[len(prefix):]
        route = route_name.replace('.', '/')
        if callable(view):
            result.append(path(route, view, name=route_name))
 
    result.sort(key=lambda x: str(x.pattern), reverse=True)
 
    return path("", include((result, namespace)))

urls.py

urlpatterns = [
    fs_paths("myapp.views", "myapp"),
]

What about path parameters?

It "just works ™️"

What about path parameters?

# myapp/views/posts/slug.py
path = "posts/<slug:slug>"

def dispatch(request, slug):
    ...

What about path parameters?

# myapp/views/projects/id.py
path = "projects/<int:id>"

def dispatch(request, id):
    ...

What about path parameters?

route = route_name.replace('.', '/')
if callable(view):
    result.append(path(route, view))

What about path parameters?

route = getattr(module, "path", route_name.replace('.', '/'))
if callable(view):
    result.append(path(route, view, name=route_name))

What about path parameters?

# myapp/views/projects/id.py
path = "<int:id>"

def dispatch(request, id):
    ...

Why dispatch?

def dispatch(request, *args, **kwargs):
    ...

Why dispatch?

def get(request, *args, **kwargs):
    ...

def post(request, *args, **kwargs):
    ...

...

Regex paths?

re_path = r"(?P<year>[0-9]{4})"

def dispatch(request, *args, **kwargs):
    ...

How can you use this?

github.com/laymonage/django-fs-paths

How can you use this?

github.com/jerivas/django-file-router

Thank you!

{
  "name": "Sage Abdullah",
  "username": "laymonage",
  "slides": {
    "hosted": "https://slides.laymonage.com/fs-paths",
    "source": "https://github.com/laymonage/slides-fs-paths"
  },
  "project": "https://github.com/laymonage/django-fs-paths",
  "alternative": "https://github.com/jerivas/django-file-router",
  "misc": {
    "jobs": "https://torchbox.com/careers",
    "wagtail": "https://wagtail.org"
  }
}