{"id":13872406,"url":"https://github.com/brokenhandsio/leaf-error-middleware","last_synced_at":"2025-10-23T16:15:24.230Z","repository":{"id":41070663,"uuid":"104588421","full_name":"brokenhandsio/leaf-error-middleware","owner":"brokenhandsio","description":"Serve up custom 404 and server error pages for your Vapor App","archived":false,"fork":false,"pushed_at":"2022-07-25T14:40:36.000Z","size":117,"stargazers_count":64,"open_issues_count":1,"forks_count":8,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-02T22:18:49.739Z","etag":null,"topics":["brokenhands","leaf","server-side-swift","swift","swift4","vapor"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brokenhandsio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-23T18:05:36.000Z","updated_at":"2025-01-29T00:17:38.000Z","dependencies_parsed_at":"2022-08-28T21:10:38.627Z","dependency_job_id":null,"html_url":"https://github.com/brokenhandsio/leaf-error-middleware","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brokenhandsio%2Fleaf-error-middleware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brokenhandsio%2Fleaf-error-middleware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brokenhandsio%2Fleaf-error-middleware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brokenhandsio%2Fleaf-error-middleware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brokenhandsio","download_url":"https://codeload.github.com/brokenhandsio/leaf-error-middleware/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247694881,"owners_count":20980733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["brokenhands","leaf","server-side-swift","swift","swift4","vapor"],"created_at":"2024-08-05T23:00:42.117Z","updated_at":"2025-10-23T16:15:19.180Z","avatar_url":"https://github.com/brokenhandsio.png","language":"Swift","funding_links":[],"categories":["Swift"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://user-images.githubusercontent.com/9938337/31054113-7cac93d8-a6a3-11e7-84ae-e98c57129a72.png\" alt=\"Leaf Error Middleware\"\u003e\n    \u003cbr\u003e\n    \u003cbr\u003e\n    \u003ca href=\"https://swift.org\"\u003e\n        \u003cimg src=\"http://img.shields.io/badge/Swift-5.6-brightgreen.svg\" alt=\"Language\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/brokenhandsio/leaf-error-middleware/actions\"\u003e\n        \u003cimg src=\"https://github.com/brokenhandsio/leaf-error-middleware/workflows/CI/badge.svg?branch=main\" alt=\"Build Status\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://codecov.io/gh/brokenhandsio/leaf-error-middleware\"\u003e\n        \u003cimg src=\"https://codecov.io/gh/brokenhandsio/leaf-error-middleware/branch/main/graph/badge.svg\" alt=\"Code Coverage\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://raw.githubusercontent.com/brokenhandsio/leaf-error-middleware/main/LICENSE\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"MIT License\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\nLeaf Error Middleware is a piece of middleware for [Vapor](https://github.com/vapor/vapor) which allows you to return custom 404 and server error pages.\n\nNote that this middleware is designed to be used for Leaf front-end websites only - it should not be used for providing JSON error responses for an API, for example.\n\n# Usage\n\nFirst, add LeafErrorMiddleware as a dependency in your `Package.swift` file:\n\n```swift\ndependencies: [\n    // ...,\n    .package(url: \"https://github.com/brokenhandsio/leaf-error-middleware.git\", from: \"4.0.0\")\n],\ntargets: [\n    .target(\n        name: \"App\", \n        dependencies: [\n            .product(name: \"Vapor\", package: \"vapor\"),\n            ..., \n            .product(name: \"LeafErrorMiddleware\", package: \"leaf-error-middleware\")\n        ]\n    ),\n    // ...\n]\n```\n\n## Default Context\n\nTo use the LeafErrorMiddleware with the default context passed to templates, register the middleware service in `configure.swift` to your `Application`'s middleware (make sure you `import LeafErrorMiddleware` at the top):\n\n```swift\napp.middleware.use(LeafErrorMiddlewareDefaultGenerator.build())\n```\n\nMake sure it appears before all other middleware to catch errors.\n\n## Custom Context\n\nLeaf Error Middleware allows you to pass a closure to `LeafErrorMiddleware` to generate a custom context for the error middleware. This is useful if you want to be able to tell if a user is logged in on a 404 page for instance.\n\nRegister the middleware as follows:\n\n```swift\nlet leafMiddleware = LeafErrorMiddleware() { status, error, req async throws -\u003e SomeContext in\n    SomeContext()\n}\napp.middleware.use(leafMiddleware)\n```\n\nThe closure receives three parameters:\n\n* `HTTPStatus` - the status code of the response returned.\n* `Error` - the error caught to be handled.\n* `Request` - the request currently being handled. This can be used to log information, make external API calls or check the session.\n\n## Custom Mappings\n\nBy default, you need to include two [Leaf](https://github.com/vapor/leaf) templates in your application:\n\n* `404.leaf`\n* `serverError.leaf`\n\nHowever, you may elect to provide a dictionary mapping arbitrary error responses (i.e \u003e= 400) to custom template names, like so:\n\n```swift\nlet mappings: [HTTPStatus: String] = [\n    .notFound: \"404\",\n    .unauthorized: \"401\",\n    .forbidden: \"403\"\n]\nlet leafMiddleware = LeafErrorMiddleware(errorMappings: mappings) { status, error, req async throws -\u003e SomeContext in\n    SomeContext()\n}\n\napp.middleware.use(leafMiddleware)\n// OR\napp.middleware.use(LeafErrorMiddlewareDefaultGenerator.build(errorMappings: mapping))\n```\n\nBy default, when Leaf Error Middleware catches a 404 error, it will return the `404.leaf` template. This particular mapping also allows returning a `401.leaf` or `403.leaf` template based on the error. Any other error caught will return the `serverError.leaf` template. By providing a mapping, you override the default 404 template and will need to respecify it if you want to use it.\n\n## Default Context\n\nIf using the default context, the `serverError.leaf` template will be passed up to three parameters in its context:\n\n* `status` - the status code of the error caught\n* `statusMessage` - a reason for the status code\n* `reason` - the reason for the error, if known. Otherwise this won't be passed in.\n\nThe `404.leaf` template and any other custom error templates will get a `reason` parameter in the context if one is known.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrokenhandsio%2Fleaf-error-middleware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrokenhandsio%2Fleaf-error-middleware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrokenhandsio%2Fleaf-error-middleware/lists"}