From aaa43be31c54243741adaf762b951fb28e240127 Mon Sep 17 00:00:00 2001 From: Manak Raj <7manakraj@gmail.com> Date: Sun, 2 Aug 2026 16:16:58 -0500 Subject: [PATCH 1/5] docs: improve middleware documentation readability Refactored middleware documentation for better readability, consistency, and beginner-friendly explanations. Improved formatting, section structure, and middleware examples. Signed-off-by: Manak Raj <7manakraj@gmail.com> --- .../docs/en/5x/guide/using-middleware.mdx | 74 ++++++++++++------- 1 file changed, 46 insertions(+), 28 deletions(-) diff --git a/src/content/docs/en/5x/guide/using-middleware.mdx b/src/content/docs/en/5x/guide/using-middleware.mdx index cd950923ee..7de65a40e9 100644 --- a/src/content/docs/en/5x/guide/using-middleware.mdx +++ b/src/content/docs/en/5x/guide/using-middleware.mdx @@ -6,18 +6,22 @@ description: Learn how to use middleware in Express.js applications, including a import Alert from '@components/primitives/Alert/Alert.astro'; import PackageManagerCommand from '@components/patterns/PackageManagerCommand/PackageManagerCommand.astro'; -Express is a routing and middleware web framework that has minimal functionality of its own: An Express application is essentially a series of middleware function calls. +Express is a lightweight routing and middleware web framework. An Express application is essentially a series of middleware function calls executed during the request-response cycle. -_Middleware_ functions are functions that have access to the [request object](/api/request) (`req`), the [response object](/api/response) (`res`), and the next middleware function in the application's request-response cycle. The next middleware function is commonly denoted by a variable named `next`. +_Middleware_ functions are functions that have access to: + +- The [request object](/api/request) (`req`) +- The [response object](/api/response) (`res`) +- The next middleware function in the application's request-response cycle, commonly named `next` Middleware functions can perform the following tasks: -- Execute any code. -- Make changes to the request and the response objects. -- End the request-response cycle. -- Call the next middleware function in the stack. +- Execute any code +- Modify the request and response objects +- End the request-response cycle +- Pass control to the next middleware function -If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. +If a middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. An Express application can use the following types of middleware: @@ -27,14 +31,20 @@ An Express application can use the following types of middleware: - [Built-in middleware](#built-in-middleware) - [Third-party middleware](#third-party-middleware) -You can load application-level and router-level middleware with an optional mount path. -You can also load a series of middleware functions together, which creates a sub-stack of the middleware system at a mount point. +You can load application-level and router-level middleware with an optional mount path. Multiple middleware functions can also be loaded together, which creates a middleware sub-stack at a mount point. ## Application-level middleware -Bind application-level middleware to an instance of the [app object](/api/application) by using the `app.use()` and `app.METHOD()` functions, where `METHOD` is the HTTP method of the request that the middleware function handles (such as GET, PUT, or POST) in lowercase. +Application-level middleware is bound to an instance of the [app object](/api/application) using: + +- `app.use()` +- `app.METHOD()` + +where `METHOD` is the lowercase HTTP method of the request that the middleware function handles, such as `get`, `post`, `put`, or `delete`. -This example shows a middleware function with no mount path. The function is executed every time the app receives a request. +### Middleware without a mount path + +The following middleware function runs every time the app receives a request: ```cjs title="index.cjs" const express = require('express'); @@ -68,8 +78,9 @@ app.use((req: Request, res: Response, next: NextFunction) => { }); ``` -This example shows a middleware function mounted on the `/user/:id` path. The function is executed for any type of -HTTP request on the `/user/:id` path. +### Middleware mounted on a path + +The following middleware function runs for any type of HTTP request on the `/user/:id` path: ```js app.use('/user/:id', (req, res, next) => { @@ -87,7 +98,9 @@ app.use('/user/:id', (req: Request, res: Response, next: NextFunction) => { }); ``` -This example shows a route and its handler function (middleware system). The function handles GET requests to the `/user/:id` path. +### Route handlers + +This example shows a route and its handler function (middleware system). The function handles GET requests to the `/user/:id` path: ```js app.get('/user/:id', (req, res, next) => { @@ -103,8 +116,9 @@ app.get('/user/:id', (req: Request, res: Response, next: NextFunction) => { }); ``` -Here is an example of loading a series of middleware functions at a mount point, with a mount path. -It illustrates a middleware sub-stack that prints request info for any type of HTTP request to the `/user/:id` path. +### Middleware sub-stacks + +Multiple middleware functions can be loaded together at a mount point to form a middleware sub-stack. This example prints request info for any type of HTTP request to the `/user/:id` path: ```js app.use( @@ -138,8 +152,6 @@ app.use( Route handlers enable you to define multiple routes for a path. The example below defines two routes for GET requests to the `/user/:id` path. The second route will not cause any problems, but it will never get called because the first route ends the request-response cycle. -This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. - ```js app.get( '/user/:id', @@ -178,7 +190,9 @@ app.get('/user/:id', (req: Request, res: Response, next: NextFunction) => { }); ``` -To skip the rest of the middleware functions from a router middleware stack, call `next('route')` to pass control to the next route. +### Skipping to the next route + +Call `next('route')` to skip the remaining middleware functions in a router middleware stack and pass control to the next route. @@ -187,7 +201,7 @@ To skip the rest of the middleware functions from a router middleware stack, cal -This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. +This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path: ```js app.get( @@ -233,9 +247,9 @@ app.get('/user/:id', (req: Request, res: Response, next: NextFunction) => { }); ``` -Middleware can also be declared in an array for reusability. +### Reusable middleware arrays -This example shows an array with a middleware sub-stack that handles GET requests to the `/user/:id` path +Middleware functions can also be grouped into arrays for better reusability. This example shows an array with a middleware sub-stack that handles GET requests to the `/user/:id` path: ```js function logOriginalUrl(req, res, next) { @@ -275,7 +289,7 @@ app.get('/user/:id', logStuff, (req: Request, res: Response, next: NextFunction) ## Router-level middleware -Router-level middleware works in the same way as application-level middleware, except it is bound to an instance of `express.Router()`. +Router-level middleware works the same way as application-level middleware, except it is bound to an instance of `express.Router()`. ```js const router = express.Router(); @@ -287,7 +301,10 @@ import express from 'express'; const router = express.Router(); ``` -Load router-level middleware by using the `router.use()` and `router.METHOD()` functions. +Load router-level middleware using: + +- `router.use()` +- `router.METHOD()` The following example code replicates the middleware system that is shown above for application-level middleware, by using router-level middleware: @@ -440,10 +457,11 @@ router.get('/user/:id', (req: Request, res: Response, next: NextFunction) => { app.use('/', router); ``` -To skip the rest of the router's middleware functions, call `next('router')` -to pass control back out of the router instance. +### Skipping out of a router + +Use `next('router')` to skip the rest of the router's middleware functions and pass control back out of the router instance. -This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. +This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path: ```cjs title="index.cjs" const express = require('express'); @@ -558,7 +576,7 @@ Use third-party middleware to add functionality to Express apps. Install the Node.js module for the required functionality, then load it in your app at the application level or at the router level. -The following example illustrates installing and loading the cookie-parsing middleware function `cookie-parser`. +The following example illustrates installing and loading the cookie-parsing middleware function `cookie-parser`: From 8c7b38a83b3889e90e1ae31fc1394011558c8621 Mon Sep 17 00:00:00 2001 From: Sebastian Beltran Date: Sun, 2 Aug 2026 16:20:29 -0500 Subject: [PATCH 2/5] docs: enhance clarity and structure in middleware guide --- .../docs/en/5x/guide/using-middleware.mdx | 24 +++++++------------ 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/src/content/docs/en/5x/guide/using-middleware.mdx b/src/content/docs/en/5x/guide/using-middleware.mdx index 7de65a40e9..c16fbcfe35 100644 --- a/src/content/docs/en/5x/guide/using-middleware.mdx +++ b/src/content/docs/en/5x/guide/using-middleware.mdx @@ -6,7 +6,7 @@ description: Learn how to use middleware in Express.js applications, including a import Alert from '@components/primitives/Alert/Alert.astro'; import PackageManagerCommand from '@components/patterns/PackageManagerCommand/PackageManagerCommand.astro'; -Express is a lightweight routing and middleware web framework. An Express application is essentially a series of middleware function calls executed during the request-response cycle. +Express is a routing and middleware web framework with minimal functionality of its own: an Express application is essentially a series of middleware function calls executed during the request-response cycle. _Middleware_ functions are functions that have access to: @@ -16,10 +16,10 @@ _Middleware_ functions are functions that have access to: Middleware functions can perform the following tasks: -- Execute any code -- Modify the request and response objects -- End the request-response cycle -- Pass control to the next middleware function +- Execute any code. +- Modify the request and response objects. +- End the request-response cycle. +- Pass control to the next middleware function. If a middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. @@ -35,12 +35,7 @@ You can load application-level and router-level middleware with an optional moun ## Application-level middleware -Application-level middleware is bound to an instance of the [app object](/api/application) using: - -- `app.use()` -- `app.METHOD()` - -where `METHOD` is the lowercase HTTP method of the request that the middleware function handles, such as `get`, `post`, `put`, or `delete`. +Bind application-level middleware to an instance of the [app object](/api/application) by using the `app.use()` and `app.METHOD()` functions, where `METHOD` is the lowercase HTTP method of the request that the middleware function handles, such as `get`, `post`, `put`, or `delete`. ### Middleware without a mount path @@ -150,6 +145,8 @@ app.use( ); ``` +### Multiple route handlers + Route handlers enable you to define multiple routes for a path. The example below defines two routes for GET requests to the `/user/:id` path. The second route will not cause any problems, but it will never get called because the first route ends the request-response cycle. ```js @@ -301,10 +298,7 @@ import express from 'express'; const router = express.Router(); ``` -Load router-level middleware using: - -- `router.use()` -- `router.METHOD()` +Load router-level middleware by using the `router.use()` and `router.METHOD()` functions. The following example code replicates the middleware system that is shown above for application-level middleware, by using router-level middleware: From e2f8d19b17d8df4fb24a7068365f752d5c68f492 Mon Sep 17 00:00:00 2001 From: Sebastian Beltran Date: Sun, 2 Aug 2026 16:43:35 -0500 Subject: [PATCH 3/5] docs: add ReadMore component and integrate into various guides --- .../patterns/ReadMore/ReadMore.astro | 37 ++++++++ src/components/patterns/ReadMore/ReadMore.css | 29 ++++++ src/components/patterns/ReadMore/index.ts | 1 + src/components/patterns/index.ts | 1 + .../docs/en/5x/guide/using-middleware.mdx | 88 ++++++++++--------- .../docs/en/5x/guide/writing-middleware.mdx | 7 +- .../docs/en/5x/starter/basic-routing.mdx | 7 +- src/content/docs/en/5x/starter/faq.mdx | 14 ++- .../docs/en/5x/starter/static-files.mdx | 5 ++ 9 files changed, 145 insertions(+), 44 deletions(-) create mode 100644 src/components/patterns/ReadMore/ReadMore.astro create mode 100644 src/components/patterns/ReadMore/ReadMore.css create mode 100644 src/components/patterns/ReadMore/index.ts diff --git a/src/components/patterns/ReadMore/ReadMore.astro b/src/components/patterns/ReadMore/ReadMore.astro new file mode 100644 index 0000000000..196609c84f --- /dev/null +++ b/src/components/patterns/ReadMore/ReadMore.astro @@ -0,0 +1,37 @@ +--- +/** + * ReadMore Pattern Component + * + * Callout block with a book icon that points readers to a related guide + * or page for further reading. Visually mirrors the Alert primitive, but + * renders as an `aside` so it stays out of the heading outline; screen + * readers announce it as complementary content labeled by the title. + * + * Write the slot content as a full sentence with the link text naming the + * target page, so both prose and link-list navigation read well. + * + * @example + * + * For more information, see the [Error handling](/guide/error-handling) guide. + * + */ + +import './ReadMore.css'; +import type { HTMLAttributes } from 'astro/types'; +import { Icon } from 'astro-icon/components'; +import { Body, Flex } from '@components/primitives'; + +type Props = { title?: string } & HTMLAttributes<'aside'>; + +const { title = 'Read more', class: className, ...rest } = Astro.props; +--- + + diff --git a/src/components/patterns/ReadMore/ReadMore.css b/src/components/patterns/ReadMore/ReadMore.css new file mode 100644 index 0000000000..d31b16b2e7 --- /dev/null +++ b/src/components/patterns/ReadMore/ReadMore.css @@ -0,0 +1,29 @@ +/** + * ReadMore Component Styles + */ + +@layer patterns { + .read-more { + display: flex; + flex-direction: column; + gap: var(--space-1); + padding: var(--space-4); + border-left-width: var(--border-width-4); + border-left-style: solid; + border-radius: 0 var(--radius-lg) var(--radius-lg) 0; + margin: var(--space-4) 0; + background-color: var(--color-bg-success); + border-color: var(--color-border-success); + } + + .read-more__icon { + flex-shrink: 0; + color: var(--color-text-success); + } + + .read-more__description { + p { + margin: 0; + } + } +} diff --git a/src/components/patterns/ReadMore/index.ts b/src/components/patterns/ReadMore/index.ts new file mode 100644 index 0000000000..10092dd7e3 --- /dev/null +++ b/src/components/patterns/ReadMore/index.ts @@ -0,0 +1 @@ +export { default as ReadMore } from './ReadMore.astro'; diff --git a/src/components/patterns/index.ts b/src/components/patterns/index.ts index 2468021e90..5fef1fe310 100644 --- a/src/components/patterns/index.ts +++ b/src/components/patterns/index.ts @@ -27,3 +27,4 @@ export { default as WriteBanner } from './WriteBanner/WriteBanner.astro'; export { default as RelatedContent } from './RelatedContent/RelatedContent.astro'; export { default as DocBottomNav } from './DocBottomNav/DocBottomNav.astro'; export { default as MiddlewareInfo } from './MiddlewareInfo/MiddlewareInfo.astro'; +export { default as ReadMore } from './ReadMore/ReadMore.astro'; diff --git a/src/content/docs/en/5x/guide/using-middleware.mdx b/src/content/docs/en/5x/guide/using-middleware.mdx index c16fbcfe35..b9bf55f1c7 100644 --- a/src/content/docs/en/5x/guide/using-middleware.mdx +++ b/src/content/docs/en/5x/guide/using-middleware.mdx @@ -5,6 +5,7 @@ description: Learn how to use middleware in Express.js applications, including a import Alert from '@components/primitives/Alert/Alert.astro'; import PackageManagerCommand from '@components/patterns/PackageManagerCommand/PackageManagerCommand.astro'; +import ReadMore from '@components/patterns/ReadMore/ReadMore.astro'; Express is a routing and middleware web framework with minimal functionality of its own: an Express application is essentially a series of middleware function calls executed during the request-response cycle. @@ -98,15 +99,15 @@ app.use('/user/:id', (req: Request, res: Response, next: NextFunction) => { This example shows a route and its handler function (middleware system). The function handles GET requests to the `/user/:id` path: ```js -app.get('/user/:id', (req, res, next) => { +app.get('/user/:id', (req, res) => { res.send('USER'); }); ``` ```ts -import { type Request, type Response, type NextFunction } from 'express'; +import { type Request, type Response } from 'express'; -app.get('/user/:id', (req: Request, res: Response, next: NextFunction) => { +app.get('/user/:id', (req: Request, res: Response) => { res.send('USER'); }); ``` @@ -156,13 +157,13 @@ app.get( console.log('ID:', req.params.id); next(); }, - (req, res, next) => { + (req, res) => { res.send('User Info'); } ); // handler for the /user/:id path, which prints the user ID -app.get('/user/:id', (req, res, next) => { +app.get('/user/:id', (req, res) => { res.send(req.params.id); }); ``` @@ -176,13 +177,13 @@ app.get( console.log('ID:', req.params.id); next(); }, - (req: Request, res: Response, next: NextFunction) => { + (req: Request, res: Response) => { res.send('User Info'); } ); // handler for the /user/:id path, which prints the user ID -app.get('/user/:id', (req: Request, res: Response, next: NextFunction) => { +app.get('/user/:id', (req: Request, res: Response) => { res.send(req.params.id); }); ``` @@ -198,7 +199,7 @@ Call `next('route')` to skip the remaining middleware functions in a router midd -This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path: +In the following example, if the user ID is `0`, the first handler skips to the next route, which sends a special response: ```js app.get( @@ -209,14 +210,14 @@ app.get( // otherwise pass the control to the next middleware function in this stack else next(); }, - (req, res, next) => { + (req, res) => { // send a regular response res.send('regular'); } ); // handler for the /user/:id path, which sends a special response -app.get('/user/:id', (req, res, next) => { +app.get('/user/:id', (req, res) => { res.send('special'); }); ``` @@ -232,14 +233,14 @@ app.get( // otherwise pass the control to the next middleware function in this stack else next(); }, - (req: Request, res: Response, next: NextFunction) => { + (req: Request, res: Response) => { // send a regular response res.send('regular'); } ); // handler for the /user/:id path, which sends a special response -app.get('/user/:id', (req: Request, res: Response, next: NextFunction) => { +app.get('/user/:id', (req: Request, res: Response) => { res.send('special'); }); ``` @@ -260,7 +261,7 @@ function logMethod(req, res, next) { } const logStuff = [logOriginalUrl, logMethod]; -app.get('/user/:id', logStuff, (req, res, next) => { +app.get('/user/:id', logStuff, (req, res) => { res.send('User Info'); }); ``` @@ -279,7 +280,7 @@ function logMethod(req: Request, res: Response, next: NextFunction) { } const logStuff = [logOriginalUrl, logMethod]; -app.get('/user/:id', logStuff, (req: Request, res: Response, next: NextFunction) => { +app.get('/user/:id', logStuff, (req: Request, res: Response) => { res.send('User Info'); }); ``` @@ -330,19 +331,19 @@ router.use( router.get( '/user/:id', (req, res, next) => { - // if the user ID is 0, skip to the next router + // if the user ID is 0, skip to the next route if (req.params.id === '0') next('route'); // otherwise pass control to the next middleware function in this stack else next(); }, - (req, res, next) => { + (req, res) => { // render a regular page res.render('regular'); } ); // handler for the /user/:id path, which renders a special page -router.get('/user/:id', (req, res, next) => { +router.get('/user/:id', (req, res) => { console.log(req.params.id); res.render('special'); }); @@ -380,19 +381,19 @@ router.use( router.get( '/user/:id', (req, res, next) => { - // if the user ID is 0, skip to the next router + // if the user ID is 0, skip to the next route if (req.params.id === '0') next('route'); // otherwise pass control to the next middleware function in this stack else next(); }, - (req, res, next) => { + (req, res) => { // render a regular page res.render('regular'); } ); // handler for the /user/:id path, which renders a special page -router.get('/user/:id', (req, res, next) => { +router.get('/user/:id', (req, res) => { console.log(req.params.id); res.render('special'); }); @@ -430,19 +431,19 @@ router.use( router.get( '/user/:id', (req: Request, res: Response, next: NextFunction) => { - // if the user ID is 0, skip to the next router + // if the user ID is 0, skip to the next route if (req.params.id === '0') next('route'); // otherwise pass control to the next middleware function in this stack else next(); }, - (req: Request, res: Response, next: NextFunction) => { + (req: Request, res: Response) => { // render a regular page res.render('regular'); } ); // handler for the /user/:id path, which renders a special page -router.get('/user/:id', (req: Request, res: Response, next: NextFunction) => { +router.get('/user/:id', (req: Request, res: Response) => { console.log(req.params.id); res.render('special'); }); @@ -455,7 +456,7 @@ app.use('/', router); Use `next('router')` to skip the rest of the router's middleware functions and pass control back out of the router instance. -This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path: +In the following example, the router only responds when the request includes an `x-auth` header. Otherwise, `next('router')` exits the router and the app responds with a 401 status: ```cjs title="index.cjs" const express = require('express'); @@ -524,15 +525,6 @@ app.use('/admin', router, (req: Request, res: Response) => { ## Error-handling middleware - - -Error-handling middleware always takes _four_ arguments. You must provide four arguments to -identify it as an error-handling middleware function. Even if you don't need to use the `next` -object, you must specify it to maintain the signature. Otherwise, the `next` object will be -interpreted as regular middleware and will fail to handle errors. - - - Define error-handling middleware functions in the same way as other middleware functions, except with four arguments instead of three, specifically with the signature `(err, req, res, next)`: ```js @@ -551,18 +543,30 @@ app.use((err: Error, req: Request, res: Response, next: NextFunction) => { }); ``` -For details about error-handling middleware, see: [Error handling](/guide/error-handling). + -## Built-in middleware +Error-handling middleware always takes _four_ arguments. You must provide four arguments to +identify it as an error-handling middleware function. Even if you don't need to use the `next` +object, you must specify it to maintain the signature. Otherwise, the `next` object will be +interpreted as regular middleware and will fail to handle errors. + + + + + +For more information, see the [Error handling](/guide/error-handling) guide. -Starting with version 4.x, Express no longer depends on [Connect](https://github.com/senchalabs/connect). The middleware -functions that were previously included with Express are now in separate modules; see [the list of middleware functions](https://github.com/senchalabs/connect#middleware). + + +## Built-in middleware Express has the following built-in middleware functions: - [express.static](/api/express/#expressstatic) serves static assets such as HTML files, images, and so on. -- [express.json](/api/express/#expressjson) parses incoming requests with JSON payloads. **NOTE: Available with Express 4.16.0+** -- [express.urlencoded](/api/express/#expressurlencoded) parses incoming requests with URL-encoded payloads. **NOTE: Available with Express 4.16.0+** +- [express.json](/api/express/#expressjson) parses incoming requests with JSON payloads. +- [express.raw](/api/express/#expressraw) parses incoming requests with Buffer payloads. +- [express.text](/api/express/#expresstext) parses incoming requests with text payloads. +- [express.urlencoded](/api/express/#expressurlencoded) parses incoming requests with URL-encoded payloads. ## Third-party middleware @@ -603,4 +607,8 @@ const app: Express = express(); app.use(cookieParser()); ``` -For a partial list of third-party middleware functions that are commonly used with Express, see: [Third-party middleware](/resources/middleware). + + +For a partial list of third-party middleware functions that are commonly used with Express, see the [Third-party middleware](/resources/middleware) page. + + diff --git a/src/content/docs/en/5x/guide/writing-middleware.mdx b/src/content/docs/en/5x/guide/writing-middleware.mdx index cc820fc025..1cdf67cf38 100644 --- a/src/content/docs/en/5x/guide/writing-middleware.mdx +++ b/src/content/docs/en/5x/guide/writing-middleware.mdx @@ -4,6 +4,7 @@ description: Learn how to write custom middleware functions for Express.js appli --- import Alert from '@components/primitives/Alert/Alert.astro'; +import ReadMore from '@components/patterns/ReadMore/ReadMore.astro'; _Middleware_ functions are functions that have access to the [request object](/api/request) (`req`), the [response object](/api/response) (`res`), and the `next` function in the application's request-response cycle. The `next` function is a function in the Express router which, when invoked, executes the middleware succeeding the current middleware. @@ -393,7 +394,11 @@ functions. Because you have access to the request object, the response object, the next middleware function in the stack, and the whole Node.js API, the possibilities with middleware functions are endless. -For more information about Express middleware, see: [Using Express middleware](/guide/using-middleware). + + +For more information about Express middleware, see the [Using Express middleware](/guide/using-middleware) guide. + + ## Configurable middleware diff --git a/src/content/docs/en/5x/starter/basic-routing.mdx b/src/content/docs/en/5x/starter/basic-routing.mdx index 2b78e00490..bc1ae79eba 100644 --- a/src/content/docs/en/5x/starter/basic-routing.mdx +++ b/src/content/docs/en/5x/starter/basic-routing.mdx @@ -4,6 +4,7 @@ description: Learn the fundamentals of routing in Express.js applications, inclu --- import Alert from '@components/primitives/Alert/Alert.astro'; +import ReadMore from '@components/patterns/ReadMore/ReadMore.astro'; _Routing_ refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (GET, POST, and so on). @@ -96,4 +97,8 @@ app.delete('/user', (req: Request, res: Response) => { }); ``` -For more details about routing, see the [routing guide](/guide/routing). + + +For more details about routing, see the [Routing](/guide/routing) guide. + + diff --git a/src/content/docs/en/5x/starter/faq.mdx b/src/content/docs/en/5x/starter/faq.mdx index d60e1d54c6..0f41b81346 100755 --- a/src/content/docs/en/5x/starter/faq.mdx +++ b/src/content/docs/en/5x/starter/faq.mdx @@ -3,6 +3,8 @@ title: FAQ description: Find answers to frequently asked questions about Express.js, including topics on application structure, models, authentication, template engines, error handling, and more. --- +import ReadMore from '@components/patterns/ReadMore/ReadMore.astro'; + ## How should I structure my application? There is no definitive answer to this question. The answer depends @@ -42,7 +44,11 @@ To normalize template engine interfaces and caching, see the [consolidate.js](https://github.com/visionmedia/consolidate.js) project for support. Unlisted template engines might still support the Express signature. -For more information, see [Using template engines with Express](/guide/using-template-engines). + + +For more information, see the [Using template engines with Express](/guide/using-template-engines) guide. + + ## How do I handle 404 responses? @@ -92,7 +98,11 @@ app.use((err: Error, req: Request, res: Response, next: NextFunction) => { }); ``` -For more information, see [Error handling](/guide/error-handling). + + +For more information, see the [Error handling](/guide/error-handling) guide. + + ## How do I render plain HTML? diff --git a/src/content/docs/en/5x/starter/static-files.mdx b/src/content/docs/en/5x/starter/static-files.mdx index fee6caa2e9..2a6a863e49 100644 --- a/src/content/docs/en/5x/starter/static-files.mdx +++ b/src/content/docs/en/5x/starter/static-files.mdx @@ -4,6 +4,7 @@ description: Understand how to serve static files like images, CSS, and JavaScri --- import Alert from '@components/primitives/Alert/Alert.astro'; +import ReadMore from '@components/patterns/ReadMore/ReadMore.astro'; To serve static files such as images, CSS files, and JavaScript files, use the `express.static` built-in middleware function in Express. @@ -85,4 +86,8 @@ import path from 'path'; app.use('/static', express.static(path.join(__dirname, 'public'))); ``` + + For more details about the `serve-static` function and its options, see [serve-static](/resources/middleware/serve-static). + + From fa86007949faa82a657d95840380a50472169b16 Mon Sep 17 00:00:00 2001 From: Sebastian Beltran Date: Sun, 2 Aug 2026 16:45:30 -0500 Subject: [PATCH 4/5] docs: integrate ReadMore component into various guides for enhanced navigation --- src/content/docs/en/4x/guide/using-middleware.mdx | 13 +++++++++++-- .../docs/en/4x/guide/writing-middleware.mdx | 7 ++++++- src/content/docs/en/4x/starter/basic-routing.mdx | 7 ++++++- src/content/docs/en/4x/starter/faq.mdx | 14 ++++++++++++-- src/content/docs/en/4x/starter/static-files.mdx | 5 +++++ 5 files changed, 40 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/4x/guide/using-middleware.mdx b/src/content/docs/en/4x/guide/using-middleware.mdx index 987633d120..c6a2f70e99 100644 --- a/src/content/docs/en/4x/guide/using-middleware.mdx +++ b/src/content/docs/en/4x/guide/using-middleware.mdx @@ -4,6 +4,7 @@ description: Learn how to use middleware in Express.js applications, including a --- import Alert from '@components/primitives/Alert/Alert.astro'; +import ReadMore from '@components/patterns/ReadMore/ReadMore.astro'; import PackageManagerCommand from '@components/patterns/PackageManagerCommand/PackageManagerCommand.astro'; Express is a routing and middleware web framework that has minimal functionality of its own: An Express application is essentially a series of middleware function calls. @@ -533,7 +534,11 @@ app.use((err: Error, req: Request, res: Response, next: NextFunction) => { }); ``` -For details about error-handling middleware, see: [Error handling](/guide/error-handling). + + +For more information, see the [Error handling](/guide/error-handling) guide. + + ## Built-in middleware @@ -585,4 +590,8 @@ const app: Express = express(); app.use(cookieParser()); ``` -For a partial list of third-party middleware functions that are commonly used with Express, see: [Third-party middleware](/resources/middleware). + + +For a partial list of third-party middleware functions that are commonly used with Express, see the [Third-party middleware](/resources/middleware) page. + + diff --git a/src/content/docs/en/4x/guide/writing-middleware.mdx b/src/content/docs/en/4x/guide/writing-middleware.mdx index 5c36b01a72..5bb9966f10 100644 --- a/src/content/docs/en/4x/guide/writing-middleware.mdx +++ b/src/content/docs/en/4x/guide/writing-middleware.mdx @@ -4,6 +4,7 @@ description: Learn how to write custom middleware functions for Express.js appli --- import Alert from '@components/primitives/Alert/Alert.astro'; +import ReadMore from '@components/patterns/ReadMore/ReadMore.astro'; _Middleware_ functions are functions that have access to the [request object](/api/request) (`req`), the [response object](/api/response) (`res`), and the `next` function in the application's request-response cycle. The `next` function is a function in the Express router which, when invoked, executes the middleware succeeding the current middleware. @@ -420,7 +421,11 @@ functions. Because you have access to the request object, the response object, the next middleware function in the stack, and the whole Node.js API, the possibilities with middleware functions are endless. -For more information about Express middleware, see: [Using Express middleware](/guide/using-middleware). + + +For more information about Express middleware, see the [Using Express middleware](/guide/using-middleware) guide. + + ## Configurable middleware diff --git a/src/content/docs/en/4x/starter/basic-routing.mdx b/src/content/docs/en/4x/starter/basic-routing.mdx index 2b78e00490..bc1ae79eba 100644 --- a/src/content/docs/en/4x/starter/basic-routing.mdx +++ b/src/content/docs/en/4x/starter/basic-routing.mdx @@ -4,6 +4,7 @@ description: Learn the fundamentals of routing in Express.js applications, inclu --- import Alert from '@components/primitives/Alert/Alert.astro'; +import ReadMore from '@components/patterns/ReadMore/ReadMore.astro'; _Routing_ refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (GET, POST, and so on). @@ -96,4 +97,8 @@ app.delete('/user', (req: Request, res: Response) => { }); ``` -For more details about routing, see the [routing guide](/guide/routing). + + +For more details about routing, see the [Routing](/guide/routing) guide. + + diff --git a/src/content/docs/en/4x/starter/faq.mdx b/src/content/docs/en/4x/starter/faq.mdx index 16863093e0..329b68ecec 100755 --- a/src/content/docs/en/4x/starter/faq.mdx +++ b/src/content/docs/en/4x/starter/faq.mdx @@ -3,6 +3,8 @@ title: FAQ description: Find answers to frequently asked questions about Express.js, including topics on application structure, models, authentication, template engines, error handling, and more. --- +import ReadMore from '@components/patterns/ReadMore/ReadMore.astro'; + ## How should I structure my application? There is no definitive answer to this question. The answer depends @@ -42,7 +44,11 @@ To normalize template engine interfaces and caching, see the [consolidate.js](https://github.com/visionmedia/consolidate.js) project for support. Unlisted template engines might still support the Express signature. -For more information, see [Using template engines with Express](/guide/using-template-engines). + + +For more information, see the [Using template engines with Express](/guide/using-template-engines) guide. + + ## How do I handle 404 responses? @@ -92,7 +98,11 @@ app.use((err: Error, req: Request, res: Response, next: NextFunction) => { }); ``` -For more information, see [Error handling](/guide/error-handling). + + +For more information, see the [Error handling](/guide/error-handling) guide. + + ## How do I render plain HTML? diff --git a/src/content/docs/en/4x/starter/static-files.mdx b/src/content/docs/en/4x/starter/static-files.mdx index fee6caa2e9..2a6a863e49 100644 --- a/src/content/docs/en/4x/starter/static-files.mdx +++ b/src/content/docs/en/4x/starter/static-files.mdx @@ -4,6 +4,7 @@ description: Understand how to serve static files like images, CSS, and JavaScri --- import Alert from '@components/primitives/Alert/Alert.astro'; +import ReadMore from '@components/patterns/ReadMore/ReadMore.astro'; To serve static files such as images, CSS files, and JavaScript files, use the `express.static` built-in middleware function in Express. @@ -85,4 +86,8 @@ import path from 'path'; app.use('/static', express.static(path.join(__dirname, 'public'))); ``` + + For more details about the `serve-static` function and its options, see [serve-static](/resources/middleware/serve-static). + + From 2ea12d420487d728f022329e3b820871c3a2f1b7 Mon Sep 17 00:00:00 2001 From: Sebastian Beltran Date: Sun, 2 Aug 2026 16:52:53 -0500 Subject: [PATCH 5/5] docs: improve clarity and structure in using middleware guide --- .../docs/en/4x/guide/using-middleware.mdx | 134 ++++++++++-------- 1 file changed, 77 insertions(+), 57 deletions(-) diff --git a/src/content/docs/en/4x/guide/using-middleware.mdx b/src/content/docs/en/4x/guide/using-middleware.mdx index c6a2f70e99..80473787a0 100644 --- a/src/content/docs/en/4x/guide/using-middleware.mdx +++ b/src/content/docs/en/4x/guide/using-middleware.mdx @@ -4,21 +4,25 @@ description: Learn how to use middleware in Express.js applications, including a --- import Alert from '@components/primitives/Alert/Alert.astro'; -import ReadMore from '@components/patterns/ReadMore/ReadMore.astro'; import PackageManagerCommand from '@components/patterns/PackageManagerCommand/PackageManagerCommand.astro'; +import ReadMore from '@components/patterns/ReadMore/ReadMore.astro'; -Express is a routing and middleware web framework that has minimal functionality of its own: An Express application is essentially a series of middleware function calls. +Express is a routing and middleware web framework with minimal functionality of its own: an Express application is essentially a series of middleware function calls executed during the request-response cycle. -_Middleware_ functions are functions that have access to the [request object](/api/request) (`req`), the [response object](/api/response) (`res`), and the next middleware function in the application's request-response cycle. The next middleware function is commonly denoted by a variable named `next`. +_Middleware_ functions are functions that have access to: + +- The [request object](/api/request) (`req`) +- The [response object](/api/response) (`res`) +- The next middleware function in the application's request-response cycle, commonly named `next` Middleware functions can perform the following tasks: - Execute any code. -- Make changes to the request and the response objects. +- Modify the request and response objects. - End the request-response cycle. -- Call the next middleware function in the stack. +- Pass control to the next middleware function. -If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. +If a middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. An Express application can use the following types of middleware: @@ -28,14 +32,15 @@ An Express application can use the following types of middleware: - [Built-in middleware](#built-in-middleware) - [Third-party middleware](#third-party-middleware) -You can load application-level and router-level middleware with an optional mount path. -You can also load a series of middleware functions together, which creates a sub-stack of the middleware system at a mount point. +You can load application-level and router-level middleware with an optional mount path. Multiple middleware functions can also be loaded together, which creates a middleware sub-stack at a mount point. ## Application-level middleware -Bind application-level middleware to an instance of the [app object](/api/application) by using the `app.use()` and `app.METHOD()` functions, where `METHOD` is the HTTP method of the request that the middleware function handles (such as GET, PUT, or POST) in lowercase. +Bind application-level middleware to an instance of the [app object](/api/application) by using the `app.use()` and `app.METHOD()` functions, where `METHOD` is the lowercase HTTP method of the request that the middleware function handles, such as `get`, `post`, `put`, or `delete`. + +### Middleware without a mount path -This example shows a middleware function with no mount path. The function is executed every time the app receives a request. +The following middleware function runs every time the app receives a request: ```cjs title="index.cjs" const express = require('express'); @@ -69,8 +74,9 @@ app.use((req: Request, res: Response, next: NextFunction) => { }); ``` -This example shows a middleware function mounted on the `/user/:id` path. The function is executed for any type of -HTTP request on the `/user/:id` path. +### Middleware mounted on a path + +The following middleware function runs for any type of HTTP request on the `/user/:id` path: ```js app.use('/user/:id', (req, res, next) => { @@ -88,24 +94,27 @@ app.use('/user/:id', (req: Request, res: Response, next: NextFunction) => { }); ``` -This example shows a route and its handler function (middleware system). The function handles GET requests to the `/user/:id` path. +### Route handlers + +This example shows a route and its handler function (middleware system). The function handles GET requests to the `/user/:id` path: ```js -app.get('/user/:id', (req, res, next) => { +app.get('/user/:id', (req, res) => { res.send('USER'); }); ``` ```ts -import { type Request, type Response, type NextFunction } from 'express'; +import { type Request, type Response } from 'express'; -app.get('/user/:id', (req: Request, res: Response, next: NextFunction) => { +app.get('/user/:id', (req: Request, res: Response) => { res.send('USER'); }); ``` -Here is an example of loading a series of middleware functions at a mount point, with a mount path. -It illustrates a middleware sub-stack that prints request info for any type of HTTP request to the `/user/:id` path. +### Middleware sub-stacks + +Multiple middleware functions can be loaded together at a mount point to form a middleware sub-stack. This example prints request info for any type of HTTP request to the `/user/:id` path: ```js app.use( @@ -137,9 +146,9 @@ app.use( ); ``` -Route handlers enable you to define multiple routes for a path. The example below defines two routes for GET requests to the `/user/:id` path. The second route will not cause any problems, but it will never get called because the first route ends the request-response cycle. +### Multiple route handlers -This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. +Route handlers enable you to define multiple routes for a path. The example below defines two routes for GET requests to the `/user/:id` path. The second route will not cause any problems, but it will never get called because the first route ends the request-response cycle. ```js app.get( @@ -148,13 +157,13 @@ app.get( console.log('ID:', req.params.id); next(); }, - (req, res, next) => { + (req, res) => { res.send('User Info'); } ); // handler for the /user/:id path, which prints the user ID -app.get('/user/:id', (req, res, next) => { +app.get('/user/:id', (req, res) => { res.send(req.params.id); }); ``` @@ -168,18 +177,20 @@ app.get( console.log('ID:', req.params.id); next(); }, - (req: Request, res: Response, next: NextFunction) => { + (req: Request, res: Response) => { res.send('User Info'); } ); // handler for the /user/:id path, which prints the user ID -app.get('/user/:id', (req: Request, res: Response, next: NextFunction) => { +app.get('/user/:id', (req: Request, res: Response) => { res.send(req.params.id); }); ``` -To skip the rest of the middleware functions from a router middleware stack, call `next('route')` to pass control to the next route. +### Skipping to the next route + +Call `next('route')` to skip the remaining middleware functions in a router middleware stack and pass control to the next route. @@ -188,7 +199,7 @@ To skip the rest of the middleware functions from a router middleware stack, cal -This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. +In the following example, if the user ID is `0`, the first handler skips to the next route, which sends a special response: ```js app.get( @@ -199,14 +210,14 @@ app.get( // otherwise pass the control to the next middleware function in this stack else next(); }, - (req, res, next) => { + (req, res) => { // send a regular response res.send('regular'); } ); // handler for the /user/:id path, which sends a special response -app.get('/user/:id', (req, res, next) => { +app.get('/user/:id', (req, res) => { res.send('special'); }); ``` @@ -222,21 +233,21 @@ app.get( // otherwise pass the control to the next middleware function in this stack else next(); }, - (req: Request, res: Response, next: NextFunction) => { + (req: Request, res: Response) => { // send a regular response res.send('regular'); } ); // handler for the /user/:id path, which sends a special response -app.get('/user/:id', (req: Request, res: Response, next: NextFunction) => { +app.get('/user/:id', (req: Request, res: Response) => { res.send('special'); }); ``` -Middleware can also be declared in an array for reusability. +### Reusable middleware arrays -This example shows an array with a middleware sub-stack that handles GET requests to the `/user/:id` path +Middleware functions can also be grouped into arrays for better reusability. This example shows an array with a middleware sub-stack that handles GET requests to the `/user/:id` path: ```js function logOriginalUrl(req, res, next) { @@ -250,7 +261,7 @@ function logMethod(req, res, next) { } const logStuff = [logOriginalUrl, logMethod]; -app.get('/user/:id', logStuff, (req, res, next) => { +app.get('/user/:id', logStuff, (req, res) => { res.send('User Info'); }); ``` @@ -269,19 +280,25 @@ function logMethod(req: Request, res: Response, next: NextFunction) { } const logStuff = [logOriginalUrl, logMethod]; -app.get('/user/:id', logStuff, (req: Request, res: Response, next: NextFunction) => { +app.get('/user/:id', logStuff, (req: Request, res: Response) => { res.send('User Info'); }); ``` ## Router-level middleware -Router-level middleware works in the same way as application-level middleware, except it is bound to an instance of `express.Router()`. +Router-level middleware works the same way as application-level middleware, except it is bound to an instance of `express.Router()`. ```js const router = express.Router(); ``` +```ts +import express from 'express'; + +const router = express.Router(); +``` + Load router-level middleware by using the `router.use()` and `router.METHOD()` functions. The following example code replicates the middleware system that is shown above for application-level middleware, by using router-level middleware: @@ -314,19 +331,19 @@ router.use( router.get( '/user/:id', (req, res, next) => { - // if the user ID is 0, skip to the next router + // if the user ID is 0, skip to the next route if (req.params.id === '0') next('route'); // otherwise pass control to the next middleware function in this stack else next(); }, - (req, res, next) => { + (req, res) => { // render a regular page res.render('regular'); } ); // handler for the /user/:id path, which renders a special page -router.get('/user/:id', (req, res, next) => { +router.get('/user/:id', (req, res) => { console.log(req.params.id); res.render('special'); }); @@ -364,19 +381,19 @@ router.use( router.get( '/user/:id', (req, res, next) => { - // if the user ID is 0, skip to the next router + // if the user ID is 0, skip to the next route if (req.params.id === '0') next('route'); // otherwise pass control to the next middleware function in this stack else next(); }, - (req, res, next) => { + (req, res) => { // render a regular page res.render('regular'); } ); // handler for the /user/:id path, which renders a special page -router.get('/user/:id', (req, res, next) => { +router.get('/user/:id', (req, res) => { console.log(req.params.id); res.render('special'); }); @@ -414,19 +431,19 @@ router.use( router.get( '/user/:id', (req: Request, res: Response, next: NextFunction) => { - // if the user ID is 0, skip to the next router + // if the user ID is 0, skip to the next route if (req.params.id === '0') next('route'); // otherwise pass control to the next middleware function in this stack else next(); }, - (req: Request, res: Response, next: NextFunction) => { + (req: Request, res: Response) => { // render a regular page res.render('regular'); } ); // handler for the /user/:id path, which renders a special page -router.get('/user/:id', (req: Request, res: Response, next: NextFunction) => { +router.get('/user/:id', (req: Request, res: Response) => { console.log(req.params.id); res.render('special'); }); @@ -435,10 +452,11 @@ router.get('/user/:id', (req: Request, res: Response, next: NextFunction) => { app.use('/', router); ``` -To skip the rest of the router's middleware functions, call `next('router')` -to pass control back out of the router instance. +### Skipping out of a router + +Use `next('router')` to skip the rest of the router's middleware functions and pass control back out of the router instance. -This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. +In the following example, the router only responds when the request includes an `x-auth` header. Otherwise, `next('router')` exits the router and the app responds with a 401 status: ```cjs title="index.cjs" const express = require('express'); @@ -507,15 +525,6 @@ app.use('/admin', router, (req: Request, res: Response) => { ## Error-handling middleware - - -Error-handling middleware always takes _four_ arguments. You must provide four arguments to -identify it as an error-handling middleware function. Even if you don't need to use the `next` -object, you must specify it to maintain the signature. Otherwise, the `next` object will be -interpreted as regular middleware and will fail to handle errors. - - - Define error-handling middleware functions in the same way as other middleware functions, except with four arguments instead of three, specifically with the signature `(err, req, res, next)`: ```js @@ -534,6 +543,15 @@ app.use((err: Error, req: Request, res: Response, next: NextFunction) => { }); ``` + + +Error-handling middleware always takes _four_ arguments. You must provide four arguments to +identify it as an error-handling middleware function. Even if you don't need to use the `next` +object, you must specify it to maintain the signature. Otherwise, the `next` object will be +interpreted as regular middleware and will fail to handle errors. + + + For more information, see the [Error handling](/guide/error-handling) guide. @@ -549,6 +567,8 @@ Express has the following built-in middleware functions: - [express.static](/api/express/#expressstatic) serves static assets such as HTML files, images, and so on. - [express.json](/api/express/#expressjson) parses incoming requests with JSON payloads. **NOTE: Available with Express 4.16.0+** +- [express.raw](/api/express/#expressraw) parses incoming requests with Buffer payloads. **NOTE: Available with Express 4.17.0+** +- [express.text](/api/express/#expresstext) parses incoming requests with text payloads. **NOTE: Available with Express 4.17.0+** - [express.urlencoded](/api/express/#expressurlencoded) parses incoming requests with URL-encoded payloads. **NOTE: Available with Express 4.16.0+** ## Third-party middleware @@ -557,7 +577,7 @@ Use third-party middleware to add functionality to Express apps. Install the Node.js module for the required functionality, then load it in your app at the application level or at the router level. -The following example illustrates installing and loading the cookie-parsing middleware function `cookie-parser`. +The following example illustrates installing and loading the cookie-parsing middleware function `cookie-parser`: