ningle-fbr

A file-based router for ningle.

Warning

This software is currently in ALPHA stage. Its APIs are subject to change.

Check the release notes for the latest updates.

What is File-Based Routing?

File-based routing automatically creates URL routes based on a project’s file and directory structure. Instead of manually configuring routes in a separate routing file, each file in a designated directory (e.g., pages or routes) becomes a route. This simplifies development and maintenance since adding, removing, or renaming a route is often just a matter of modifying a file’s name or location.

Usage

To use ningle-fbr, set up your project using the package-inferred-system style.

Example directory structure:

example.asd
src/
  app.lisp
  routes/
    index.lisp
    hello.lisp
    users/
      index.lisp
      <id>.lisp
    nested/
      page.lisp

example.asd:

(defsystem "example"
  :class :package-inferred-system
  :pathname "src"
  :depends-on ("example/app"))

/src/app.lisp:

(defpackage #:example
  (:nicknames #:example/app)
  (:use #:cl)
  (:import-from #:ningle)
  (:import-from #:ningle-fbr #:set-routes))
(in-package #:example/app)

(defparameter *app* (make-instance 'ningle:<app>))

(set-routes *app* :system :example :target-dir-path "routes")

Static Routing

Routes are determined by packages located under :example/routes. The package’s name corresponds directly to a URL path:

• :example/routes/index → /
• :example/routes/hello → /hello
• :example/routes/users/index → /users
• :example/routes/nested/page → /nested/page

/src/routes/index.lisp:

(defpackage #:example/routes/index
  (:use #:cl)
  (:export #:handle-get
           #:handle-post
           #:handle-put
           #:handle-delete))
(in-package #:example/routes/index)

(defun handle-get (params)
  ;; Implement GET logic here
  )

(defun handle-post (params)
  ;; Implement POST logic here
  )

(defun handle-put (params)
  ;; Implement PUT logic here
  )

(defun handle-delete (params)
  ;; Implement DELETE logic here
  )

Handlers are chosen based on the HTTP method. If handle-get is exported, it will be called for GET requests on /.

Dynamic Routing

To define dynamic routes, use <> in the file name to indicate URL parameters.

For example: :example/routes/user/<id> → /user/:id

If a request comes in at /user/123, params will include :id "123".

404 Handling

To handle 404 (Not Found) errors, create a special package named :example/routes/not-found and define handle-not-found:

(defpackage #:example/routes/not-found
  (:use #:cl)
  (:export #:handle-not-found))
(in-package #:example/routes/not-found)

(defun handle-not-found ()
  ;; Implement custom 404 logic here
  )

License

Licensed under the MIT License.

© 2024, skyizwhite.