diff --git a/_includes/readmes/cors.md b/_includes/readmes/cors.md index c6d26cac..527a0f31 100644 --- a/_includes/readmes/cors.md +++ b/_includes/readmes/cors.md @@ -16,7 +16,7 @@ CORS is a node.js package for providing a [Connect](http://www.senchalabs.org/co * [Configuring CORS](#configuring-cors) * [Configuring CORS w/ Dynamic Origin](#configuring-cors-w-dynamic-origin) * [Enabling CORS Pre-Flight](#enabling-cors-pre-flight) - * [Configuring CORS Asynchronously](#configuring-cors-asynchronously) + * [Customizing CORS Settings Dynamically per Request](#customizing-cors-settings-dynamically-per-request) * [Configuration Options](#configuration-options) * [License](#license) * [Author](#author) @@ -69,6 +69,8 @@ app.listen(80, function () { ### Configuring CORS +See the [configuration options](#configuration-options) for details. + ```javascript var express = require('express') var cors = require('cors') @@ -161,27 +163,45 @@ NOTE: When using this middleware as an application level middleware (for example, `app.use(cors())`), pre-flight requests are already handled for all routes. -### Configuring CORS Asynchronously +### Customizing CORS Settings Dynamically per Request + +For APIs that require different CORS configurations for specific routes or requests, you can dynamically generate CORS options based on the incoming request. The `cors` middleware allows you to achieve this by passing a function instead of static options. This function is called for each incoming request and must use the callback pattern to return the appropriate CORS options. + +The function accepts: +1. **`req`**: + - The incoming request object. + +2. **`callback(error, corsOptions)`**: + - A function used to return the computed CORS options. + - **Arguments**: + - **`error`**: Pass `null` if there’s no error, or an error object to indicate a failure. + - **`corsOptions`**: An object specifying the CORS policy for the current request. + +Here’s an example that handles both public routes and restricted, credential-sensitive routes: ```javascript -var express = require('express') -var cors = require('cors') -var app = express() - -var allowlist = ['http://example1.com', 'http://example2.com'] -var corsOptionsDelegate = function (req, callback) { +var dynamicCorsOptions = function(req, callback) { var corsOptions; - if (allowlist.indexOf(req.header('Origin')) !== -1) { - corsOptions = { origin: true } // reflect (enable) the requested origin in the CORS response + if (req.path.startsWith('/auth/connect/')) { + corsOptions = { + origin: 'http://mydomain.com', // Allow only a specific origin + credentials: true, // Enable cookies and credentials + }; } else { - corsOptions = { origin: false } // disable CORS for this request + corsOptions = { origin: '*' }; // Allow all origins for other routes } - callback(null, corsOptions) // callback expects two parameters: error and options -} + callback(null, corsOptions); +}; -app.get('/products/:id', cors(corsOptionsDelegate), function (req, res, next) { - res.json({msg: 'This is CORS-enabled for an allowed domain.'}) -}) +app.use(cors(dynamicCorsOptions)); + +app.get('/auth/connect/twitter', function (req, res) { + res.send('CORS dynamically applied for Twitter authentication.'); +}); + +app.get('/public', function (req, res) { + res.send('Public data with open CORS.'); +}); app.listen(80, function () { console.log('CORS-enabled web server listening on port 80') @@ -192,7 +212,9 @@ app.listen(80, function () { * `origin`: Configures the **Access-Control-Allow-Origin** CORS header. Possible values: - `Boolean` - set `origin` to `true` to reflect the [request origin](http://tools.ietf.org/html/draft-abarth-origin-09), as defined by `req.header('Origin')`, or set it to `false` to disable CORS. - - `String` - set `origin` to a specific origin. For example if you set it to `"http://example.com"` only requests from "http://example.com" will be allowed. + - `String` - set `origin` to a specific origin. For example, if you set it to + - `"http://example.com"` only requests from "http://example.com" will be allowed. + - `"*"` for all domains to be allowed. - `RegExp` - set `origin` to a regular expression pattern which will be used to test the request origin. If it's a match, the request origin will be reflected. For example the pattern `/example\.com$/` will reflect any request that is coming from an origin ending with "example.com". - `Array` - set `origin` to an array of valid origins. Each origin can be a `String` or a `RegExp`. For example `["http://example1.com", /\.example2\.com$/]` will accept any request from "http://example1.com" or from a subdomain of "example2.com". - `Function` - set `origin` to a function implementing some custom logic. The function takes the request origin as the first parameter and a callback (called as `callback(err, origin)`, where `origin` is a non-function value of the `origin` option) as the second. diff --git a/_includes/readmes/method-override.md b/_includes/readmes/method-override.md index 830b2ee0..ce96a96c 100644 --- a/_includes/readmes/method-override.md +++ b/_includes/readmes/method-override.md @@ -67,9 +67,9 @@ typically be used in conjunction with `XMLHttpRequest` on implementations that do not support the method you are trying to use. ```js -var express = require('express') -var methodOverride = require('method-override') -var app = express() +const express = require('express') +const methodOverride = require('method-override') +const app = express() // override with the X-HTTP-Method-Override header in the request app.use(methodOverride('X-HTTP-Method-Override')) @@ -80,7 +80,7 @@ Example call with header override using `XMLHttpRequest`: ```js -var xhr = new XMLHttpRequest() +const xhr = new XMLHttpRequest() xhr.onload = onload xhr.open('post', '/resource', true) xhr.setRequestHeader('X-HTTP-Method-Override', 'DELETE') @@ -102,9 +102,9 @@ query value would typically be used in conjunction with plain HTML newer methods. ```js -var express = require('express') -var methodOverride = require('method-override') -var app = express() +const express = require('express') +const methodOverride = require('method-override') +const app = express() // override with POST having ?_method=DELETE app.use(methodOverride('_method')) @@ -121,9 +121,9 @@ Example call with query override using HTML `
`: ### multiple format support ```js -var express = require('express') -var methodOverride = require('method-override') -var app = express() +const express = require('express') +const methodOverride = require('method-override') +const app = express() // override with different headers; last one takes precedence app.use(methodOverride('X-HTTP-Method')) // Microsoft @@ -137,10 +137,10 @@ You can implement any kind of custom logic with a function for the `getter`. The implements the logic for looking in `req.body` that was in `method-override@1`: ```js -var bodyParser = require('body-parser') -var express = require('express') -var methodOverride = require('method-override') -var app = express() +const bodyParser = require('body-parser') +const express = require('express') +const methodOverride = require('method-override') +const app = express() // NOTE: when using req.body, you must fully parse the request body // before you call methodOverride() in your middleware stack, @@ -149,7 +149,7 @@ app.use(bodyParser.urlencoded()) app.use(methodOverride(function (req, res) { if (req.body && typeof req.body === 'object' && '_method' in req.body) { // look in urlencoded POST bodies and delete it - var method = req.body._method + const method = req.body._method delete req.body._method return method } diff --git a/_includes/readmes/serve-favicon.md b/_includes/readmes/serve-favicon.md index ce8daa83..a7f94b45 100644 --- a/_includes/readmes/serve-favicon.md +++ b/_includes/readmes/serve-favicon.md @@ -3,8 +3,8 @@ [![NPM Version][npm-image]][npm-url] [![NPM Downloads][downloads-image]][downloads-url] [![Linux Build Status][ci-image]][ci-url] -[![Windows Build][appveyor-image]][appveyor-url] [![Coverage Status][coveralls-image]][coveralls-url] +[![OpenSSF Scorecard Badge][ossf-scorecard-badge]][ossf-scorecard-visualizer] Node.js middleware for serving a favicon. @@ -124,8 +124,6 @@ server.listen(3000) [MIT](LICENSE) -[appveyor-image]: https://img.shields.io/appveyor/ci/dougwilson/serve-favicon/master.svg?label=windows -[appveyor-url]: https://ci.appveyor.com/project/dougwilson/serve-favicon [ci-image]: https://badgen.net/github/checks/expressjs/serve-favicon/master?label=ci [ci-url]: https://github.com/expressjs/serve-favicon/actions/workflows/ci.yml [coveralls-image]: https://img.shields.io/coveralls/expressjs/serve-favicon.svg @@ -134,3 +132,5 @@ server.listen(3000) [downloads-url]: https://npmjs.org/package/serve-favicon [npm-image]: https://img.shields.io/npm/v/serve-favicon.svg [npm-url]: https://npmjs.org/package/serve-favicon +[ossf-scorecard-badge]: https://api.scorecard.dev/projects/github.com/expressjs/serve-favicon/badge +[ossf-scorecard-visualizer]: https://ossf.github.io/scorecard-visualizer/#/projects/github.com/expressjs/serve-favicon diff --git a/en/resources/contributing.md b/en/resources/contributing.md index ca3bd726..03b5fad1 100644 --- a/en/resources/contributing.md +++ b/en/resources/contributing.md @@ -339,15 +339,13 @@ pull request. ### The Official Documentation of the Express JS Framework -This is the contribution documentation for the [Expressjs.com](https://github.com/expressjs/expressjs.com) website. +This is the contribution documentation for the [expressjs.com](https://github.com/expressjs/expressjs.com) website. #### Need some ideas? These are some typical issues. -1. **Website issues**: -If you see anything on the site that could use a tune-up, think about how to fix it. - +1. **Website issues**: If you see anything on the site that could use a tune-up, think about how to fix it. - Display or screen sizing problems - Mobile responsiveness issues - Missing or broken accessibility features @@ -355,22 +353,15 @@ If you see anything on the site that could use a tune-up, think about how to fix - Broken links - Page structure or user interface enhancements - -2. **Content Issues**: -Fix anything related to site content or typos. +2. **Content Issues**: Fix anything related to site content or typos. - Spelling errors - Incorrect/outdated Express JS documentation - Missing content - 3. **Translation Issues**: Fix any translation errors or contribute new content. - Fix spelling errors - Fix incorrect/poorly translated words - - Translate new content -> **IMPORTANT:** -> All translation submissions are currently paused. See this [notice](#notice-we-have-paused-all-translation-contributions) for more information. - - - Check out the [Contributing translations](#contributing-translations) section below for a contributing guide. + - Check out the [Contributing translations](#contributing-translations) section below for a contributing guide. #### Want to work on a backlog issue? @@ -380,6 +371,7 @@ We often have bugs or enhancements that need work. You can find these under our If you've found a bug or a typo, or if you have an idea for an enhancement, you can: - Submit a [new issue](https://github.com/expressjs/expressjs.com/issues/new/choose) on our repo. Do this for larger proposals, or if you'd like to discuss or get feedback first. + - Make a [Github pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). If you have already done work and it's ready to go, feel free to send it our way. ## Getting Started @@ -400,7 +392,9 @@ So you've found a problem that you want to fix, or have a site enhancement you w Clone the repo and get the code: - git clone https://github.com/expressjs/expressjs.com.git +```sh +git clone https://github.com/expressjs/expressjs.com.git +``` After you've got the code you're ready to start making your changes! @@ -426,14 +420,16 @@ follow the specific instructions for [How to write a blog post.](https://express **CSS or Javascript** - All css and js files are kept in `css` and `js` folders on the project root. -The Express JS website is build using [Jeykyll](https://jekyllrb.com/) and is hosted on [Github Pages](https://pages.github.com/). +The Express JS website is built using [Jekyll](https://jekyllrb.com/) and is hosted on [Github Pages](https://pages.github.com/). #### Step 3: Running the Application - Now you'll need a way to see your changes, which means you'll need a running version of the application. You have two options. -1. __Run Locally__: This gets the local version of the application up and running on your machine. Follow our [Local Setup Guide](https://github.com/expressjs/expressjs.com?tab=readme-ov-file#local-setup) to use this option. + + +1. __Run Locally__: This gets the local version of the application up and running on your machine. Follow our [Local Setup Guide](https://github.com/expressjs/expressjs.com?tab=readme-ov-file#build-the-website-locally) to use this option. - This is the recommended option for moderate to complex work. + 2. __Run using Deploy Preview__: Use this option if you don't want to bother with a local installation. Part of our continuous integration pipeline includes [Netlify Deploy Preview](https://docs.netlify.com/site-deploys/deploy-previews/). 1. To use this you'll need to get your changes online - after you've made your first commit on your feature branch, make a *draft* pull request. 2. After the build steps are complete, you'll have access to a __Deploy Preview__ tab that will run your changes on the web, rebuilding after each commit is pushed. @@ -441,49 +437,24 @@ Now you'll need a way to see your changes, which means you'll need a running ver ## Contributing translations -#### Notice: We have paused all translation contributions. -> **IMPORTANT:** -> We are currently working toward a more streamlined translations workflow. As long as this notice is posted, we will _not_ be accepting any translation submissions. - -We highly encourage community translations! We no longer have professional translations, and we believe in the power of our community to provide accurate and helpful translations. +We use Crowdin to manage our translations in multiple languages and achieve automatic translation with artificial intelligence. Since these translations can be inefficient in some cases, we need help from the community to provide accurate and helpful translations. The documentation is translated into these languages: + +- Chinese Simplified (`zh-cn`) +- Chinese Traditional (`zh-tw`) - English (`en`) -- Spanish (`es`) - French (`fr`) +- German (`de`) - Italian (`it`) -- Indonesian (`id`) - Japanese (`ja`) - Korean (`ko`) - Brazilian Portuguese (`pt-br`) -- Russian (`ru`) -- Slovak (`sk`) -- Thai (`th`) -- Turkish (`tr`) -- Ukrainian (`uk`) -- Uzbek (`uz`) -- Simplified Chinese (`zh-cn`) -- Traditional Chinese (`zh-tw`) +- Spanish (`es`) -### Adding New Full Site Translations +### How to translate -If you find a translation is missing from the list you can create a new one. +1. Request to join the Express.js Website project on [Crowdin](https://express.crowdin.com/website) +2. [Select the language you want to translate](https://support.crowdin.com/joining-translation-project/#starting-translation) +3. [Start translating](https://support.crowdin.com/online-editor/) -To translate Expressjs.com into a new language, follow these steps: - -1. Clone the [`expressjs.com`](https://github.com/expressjs/expressjs.com) repository. -2. Create a directory for the language of your choice using its [ISO 639-1 code](https://www.loc.gov/standards/iso639-2/php/code_list.php) as its name. -3. Copy `index.md`, `api.md`, `starter/`, `guide/`, `advanced/`, `resources/`, `4x/`, and `3x/`, to the language directory. -4. Remove the link to 2.x docs from the "API Reference" menu. -5. Update the `lang` variable in the copied markdown files. -6. Update the `title` variable in the copied markdown files. -7. Create the header, footer, notice, and announcement file for the language in the `_includes/` directory, in the respective directories, and make necessary edits to the contents. -8. Create the announcement file for the language in the `_includes/` directory. -9. Make sure to append `/{{ page.lang }}` to all the links within the site. -10. Update the [CONTRIBUTING.md](https://github.com/expressjs/expressjs.com/blob/gh-pages/CONTRIBUTING.md#contributing-translations) and the `.github/workflows/translation.yml` files with the new language. - -### Adding Page and Section Translations - -Many site translations are still missing pages. To find which ones we need help with, you can [filter for merged PRs](https://github.com/expressjs/expressjs.com/pulls?q=is%3Apr+is%3Aclosed+label%3Arequires-translation-es) that include the tag for your language, such as `requires-translation-es` for requires Spanish translation. - -If you contribute a page or section translation, please reference the original PR. This helps the person merging your translation to remove the tag from the original PR.