Create new versioned docs for single-spa@6

blog/2023-11-27-single-spa-6.md

@@ -0,0 +1,243 @@
+---
+title: single-spa 6
+author: Joel Denning
+authorURL: https://x.com/joelbdenning
+authorImageURL: https://avatars2.githubusercontent.com/u/5524384?s=460&v=4
+---
+
+# Announcing single-spa@6
+
+We have released single-spa@6! The single-spa core team is committed to a stable single-spa runtime with very few breaking changes. We expect over 95% of single-spa users can upgrade easily without altering their changes!
+
+## Summary
+
+single-spa@6 provides advanced features such as async navigation cancelation and parcel-only mode (via `patchHistoryApi`), while also updating the package configuration to use modern NodeJS and bundler features like [package entrypoints](https://nodejs.org/dist/latest-v16.x/docs/api/packages.html#packages_package_entry_points) and [`"type": "module"`](https://nodejs.org/dist/latest-v16.x/docs/api/packages.html#packages_type). We also updated `urlRerouteOnly` to default to `true`, as it boosts performance and we consider it to be a best practice to author applications that work when urlRerouteOnly is set to true.
+
+## Browser Support / IE11
+
+**We still support IE11** and the same versions of NodeJS (at least as old as Node 10). However, we've changed our defaults such that IE11 is only supported with some additional configuration, as described in the IE11 Migration section below.
+
+For the `single-spa` npm package, we plan single-spa@6 to be the last major version that supports IE11. In general, we've released a major version of single-spa every 1-2 years. We do not have a concrete timeline or plans for single-spa@7, and will accept community contributions for any important patches to single-spa@6 after single-spa@7 is released.
+
+For all surrounding packages (single-spa-react, single-spa-vue, systemjs-webpack-interop, single-spa-angular, etc) we may begin dropping IE11 support sooner than the single-spa@7 release. As we do so, we'll create documentation that lists the latest versions of packages that support IE11, and also accept community contributions to those versions for important updates.
+
+The motivation for dropping IE11 support over time is to allow our core team to spend less time on supporting a nine year old browser and more time pushing the single-spa ecosystem forward. Also, we believe that the majority of end users should not suffer performance penalties because of a small percentage of users still using IE11. Slowly dropping IE11 also will also allow us to focus on a systemjs-less future for single-spa, where native browser modules are used rather than systemjs modules.
+
+We understand and sympathize with companies who cannot drop IE11 support now, which is why we're supporting IE11 even though much of the ecosystem has already dropped it (Vue 3 does not support ie11, Angular only does after some effort, and even webpack 5 requires extra configuration to get it working in IE11). Many of single-spa's users are large financial institutions, large ecommerce companies, and other very large companies, where dropping IE11 support is a long process that involves many dozens of people from separate departments. We encourage single-spa users to start the conversations at your companies about dropping IE11 support, even if they take a long time or result in a decision to drop IE11 years in the future.
+
+## Migration
+
+We think that >95% of single-spa users will be able to safely upgrade with no code changes. The breaking changes below are largely related to advanced features that most single-spa users do not use.
+
+### Steps
+
+1. If using SystemJS + import maps, change the URL of single-spa in your import map:
+
+```diff
+<script type="systemjs-importmap">
+  {
+    "imports": {
+-     "single-spa": "https://cdn.jsdelivr.net/npm/[email protected]/lib/system/single-spa.min.js"
++     "single-spa": "https://cdn.jsdelivr.net/npm/[email protected]/lib/es2015/system/single-spa.min.js"
+    }
+  }
+</script>
+```
+
+2. In all your microfrontends (including root config), upgrade single-spa:
+
+```sh
+npm install single-spa@6
+yarn add single-spa@6
+pnpm install single-spa@6
+```
+
+3. Test things out.
+4. If your app is not re-rendering during route transitions like it should (this is most common for Angular apps, but can happen in other frameworks to if you do a route transition without modifying the URL), change your root config's call to `start()`
+
+```diff
+import { start } from 'single-spa';
+
+// DO NOT MAKE THIS CHANGE unless you are experiencing problems.
+- start();
++ start({
++   urlRerouteOnly: false
++ });
+```
+
+That's it! If you experience other issues, let us know in Github issues.
+
+### IE11
+
+If you support IE11, use the `es5` version of single-spa rather than `es2015`. The method of doing this depends on your configuration - some common ones are explained below:
+
+#### Import Maps
+
+```diff
+<script type="systemjs-importmap">
+  {
+    "imports": {
+-     "single-spa": "https://cdn.jsdelivr.net/npm/[email protected]/lib/es2015/system/single-spa.min.js"
++     "single-spa": "https://cdn.jsdelivr.net/npm/[email protected]/lib/es5/system/single-spa.min.js"
+    }
+  }
+</script>
+```
+
+#### Webpack
+
+If externalizing single-spa in your webpack config (very common, and the default with webpack-config-single-spa), you do not need to make the changes below. Otherwise, though, these changes will ensure you use the IE11-compatible version of single-spa.
+
+```js
+// webpack.config.js
+module.exports = {
+  resolve: {
+    "alias": {
+      "single-spa": require.resolve("single-spa/lib/es5/esm/single-spa.min.js")
+    }
+  }
+}
+```
+
+#### Rollup
+
+Use https://www.npmjs.com/package/@rollup/plugin-alias to alias the import similarly to webpack
+
+#### Import
+
+If you do not wish to change bundler configuration, you can modify your import statements.
+
+```diff
+- import { start } from 'single-spa';
++ import { start } from 'single-spa/lib/es5/esm/single-spa.min.js';
+```
+
+## Breaking Changes
+
+- single-spa's package.json's `"main"` field now points to an es2015 version of single-spa that does not work in IE11. To support IE11, see section below.
+- Delay patching history api until start() or patchHistoryApi() is called. [Github link](https://github.com/single-spa/single-spa/pull/827)
+- Do not show start() warning when registerApplication hasn't been called (for parcel-only use cases) [Github link](https://github.com/single-spa/single-spa/pull/827)
+- Change urlRerouteOnly default value to true. This is a performance boost for most applications, but for some situations can result in single-spa not triggering mounts/unmounts when it should. You can read more about it at https://single-spa.js.org/docs/api#start and https://github.com/single-spa/single-spa/issues/484. Angular users may want to set it to false due to nuanced behavior of angular router. To do so, call `start({urlRerouteOnly: false})` in your root config. [Github link](https://github.com/single-spa/single-spa/pull/828)
+- `cancelNavigation(val)` no longer cancels navigation if `val` is falsy [Github link](https://github.com/single-spa/single-spa/pull/826)
+- single-spa's package.json `"type"` is now set to `"module"`. This only impacts NodeJS usage of single-spa (not webpack/rollup/browser). Read more at [official nodejs docs](https://nodejs.org/dist/latest-v16.x/docs/api/packages.html#packages_type).
+- single-spa's package.json now has `"exports"`. This changes which of single-spa's bundles are used by NodeJS, webpack, and rollup. The main change is that webpack / rollup will now use an IE11-incompatible (es2015) version of single-spa. See IE11 section below for more details. Additionally, an ESM version of single-spa will now be used when loaded via `import('single-spa')` or `import 'single-spa';`, whereas a UMD version will be used when calling `require("single-spa')`. To avoid the [dual package hazard](https://nodejs.org/dist/latest-v16.x/docs/api/packages.html#packages_dual_commonjs_es_module_packages), only use `import` or `require` to load single-spa in your NodeJS code - do not use both. You can see the package exports at https://github.com/single-spa/single-spa/blob/dea22f1aac39777a07252897ae625ab1d8313e9d/package.json#L8-L25.
+- The published `umd` builds now have `.cjs` extensions rather than `.js`, since all `.js` files in the single-spa package are assumed to be ESM.
+
+```sh
+File structure published to npm
+
+# Before
+# See https://www.jsdelivr.com/package/npm/single-spa?path=lib&version=5.9.3
+lib/
+  # IE11
+  umd/
+    single-spa.dev.js
+    single-spa.min.js
+  # IE11
+  esm/
+    single-spa.dev.js
+    single-spa.min.js
+  # IE11
+  system/
+    single-spa.dev.js
+    single-spa.min.js
+  # No IE11
+  es2015/
+    single-spa.dev.js
+    single-spa.min.js
+
+# After
+# See https://www.jsdelivr.com/package/npm/single-spa?path=lib&version=6.0.0
+lib
+  # IE11
+  es5/
+    umd/
+      single-spa.dev.js
+      single-spa.min.js
+    system/
+      single-spa.dev.js
+      single-spa.min.js
+    esm/
+      single-spa.dev.js
+      single-spa.min.js
+  # No IE11
+  es2015/
+    umd/
+      single-spa.dev.cjs
+      single-spa.min.cjs
+    system/
+      single-spa.dev.js
+      single-spa.min.js
+    esm/
+      single-spa.dev.js
+      single-spa.min.js
+```
+
+## Features
+
+## Async navigation cancelation
+
+We've added support for async navigation cancelation. To use it, call `cancelNavigation(promise)` with a promise as an argument. Single-spa will wait until that promise resolves/rejects before proceeding with navigation. If the promise resolves with a truthy value, navigation is canceled. If the promise resolves with a falsy value or rejects, navigation is not canceled.  [Github link](https://github.com/single-spa/single-spa/pull/826)
+
+```js
+window.addEventListener("single-spa:before-routing-event", evt => {
+  if (evt.detail.oldUrl === "/settings") {
+    evt.detail.cancelNavigation(checkSettingsOkay())
+  }
+})
+
+async function checkSettingsOkay() {
+  const response = await fetch('/api/settings-okay')
+  if (response.ok) {
+    return true;
+  } else {
+    alert("Please fix your settings before leaving the page");
+    return false
+  }
+}
+```
+
+### New patchHistoryApi
+
+We've exposed a new `patchHistoryApi()` api. This lets you use single-spa's modified implementations of pushState/replaceState/popstate/hashchange without using single-spa applications. This is intended to be used by single-spa users who exclusively use single-spa parcels, rather than applications [Github link](https://github.com/single-spa/single-spa/pull/827)
+
+```js
+import { patchHistoryApi, mountRootParcel } from 'single-spa';
+
+patchHistoryApi({
+  urlRerouteOnly: true
+})
+
+// now you don't need to call start() if you're only using parcels
+
+mountRootParcel(parcelConfig, parcelProps)
+```
+
+### New profiler
+
+We've implemented a profiler that is available within the dev builds of single-spa@6. A visualization of the profiler is available in the [email protected] browser extension:
+
+- Implement profiler for lifecycle events. by @joeldenning in [#868](https://github.com/single-spa/single-spa/pull/868)
+- Implement parcel and routing profiler events. by @joeldenning in [#903](https://github.com/single-spa/single-spa/pull/903)
+
+<img src="/img/profiler-screenshot.png" alt="Screenshot of single-spa-inspector profiler tab" />
+
+## Fixes
+
+- Fix regression with parcel name [Github link](https://github.com/single-spa/single-spa/pull/825)
+- Ensure all reroute promises (triggerAppChange() return value) resolve even during cancelation [Github link](https://github.com/single-spa/single-spa/pull/831)
+- fix(types): fix SingleSpaAppsByNewStatus interface by @FelixGraf in [#988](https://github.com/single-spa/single-spa/pull/988)
+- Ensure app is unmounted during unregisterApplication. Resolves #871 by @joeldenning in [#875](https://github.com/single-spa/single-spa/pull/875)
+
+## Maintenance
+
+- Switch from yarn -> pnpm [Github link](https://github.com/single-spa/single-spa/pull/824)
+- Upgrade all dependencies [Github link](https://github.com/single-spa/single-spa/pull/824)
+- Upgrade husky from v4 to v7. Use pinst to avoid issues with yarn 2 users as described in https://typicode.github.io/husky/#/?id=yarn-2 [Github link](https://github.com/single-spa/single-spa/pull/824)
+- Upgrade to Jest 27. Fix tests to work with Jest 27. [Github link](https://github.com/single-spa/single-spa/pull/824)
+- Upgrade to Node 16. Fix tests to work with Node 16 (Fix tests in Node 15 #652) [Github link](https://github.com/single-spa/single-spa/pull/824)
+- Run upgraded version of prettier on all files. [Github link](https://github.com/single-spa/single-spa/pull/824)
+- Remove unused babel-eslint dependency [Github link](https://github.com/single-spa/single-spa/pull/824)
+- Upgrade to new package names for all rollup plugins. (@rollup/plugin-node-resolve instead of rollup-plugin-node-resolve) [Github link](https://github.com/single-spa/single-spa/pull/824)
+- Remove file size impact workflow since it's broken. by @joeldenning in [#879](https://github.com/single-spa/single-spa/pull/879)
+- Remove console.log in test by @joeldenning in [#878](https://github.com/single-spa/single-spa/pull/878)

versioned_docs/version-6.x/CODE_OF_CONDUCT.md

@@ -0,0 +1,47 @@
+---
+id: code-of-conduct
+title: Code of Conduct
+sidebar_label: Code of Conduct
+---
+
+This code of conduct outlines our expectations for participants within the single-spa community, as well as steps to reporting unacceptable behavior. We are committed to providing a welcoming and inspiring community for all and expect our code of conduct to be honored. Anyone who violates this code of conduct may be banned from the community.
+
+Our open source community strives to:
+
+* **Be friendly and patient.**
+* **Be welcoming:** We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, color, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability.
+* **Be considerate:** Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into *account when making decisions. Remember that we’re a world-wide community, so you might not be communicating in someone else’s primary language.
+* **Be respectful:** Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration *to turn into a personal attack. It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one.
+* **Be careful in the words that you choose:** we are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other *exclusionary behavior aren’t acceptable. This includes, but is not limited to:
+  * Violent threats or language directed against another person.
+  * Discriminatory jokes and language.
+  * Posting sexually explicit or violent material.
+  * Posting (or threatening to post) other people’s personally identifying information (“doxing”).
+  * Personal insults, especially those using racist or sexist terms.
+  * Unwelcome sexual attention.
+  * Advocating for, or encouraging, any of the above behavior.
+  * Repeated harassment of others. In general, if someone asks you to stop, then stop.
+  * **When we disagree, try to understand why:** Disagreements, both social and technical, happen all the time. It is important that we resolve disagreements and differing views constructively.
+  * **Remember that we’re different.** The strength of our community comes from its diversity, people from a wide range of backgrounds. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that it is human to err and blaming each other doesn’t get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes.
+
+This code is not exhaustive or complete. It serves to distill our common understanding of a collaborative, shared environment, and goals. We expect it to be followed in spirit as much as in the letter.
+
+## Diversity Statement
+
+We encourage everyone to participate and are committed to building a community for all. Although we may not be able to satisfy everyone, we all agree that everyone is equal. Whenever a participant has made a mistake, we expect them to take responsibility for it. If someone has been harmed or offended, it is our responsibility to listen carefully and respectfully, and do our best to right the wrong.
+
+Although this list cannot be exhaustive, we explicitly honor diversity in age, gender, gender identity or expression, culture, ethnicity, language, national origin, political beliefs, profession, race, religion, sexual orientation, socioeconomic status, and technical ability. We will not tolerate discrimination based on any of the protected characteristics above, including participants with disabilities.
+
+## Reporting Issues
+
+If you experience or witness unacceptable behavior—or have any other concerns—please report it by sending a Twitter DM to https://twitter.com/Single_spa. All reports will be handled with discretion. In your report please include:
+
+* Your contact information.
+* Names (real, nicknames, or pseudonyms) of any individuals involved. If there are additional witnesses, please include them as well. Your account of what occurred, and if you believe the incident is ongoing. If there is a publicly available record (e.g. a mailing list archive or a public IRC logger), please include a link.
+* Any additional information that may be helpful.
+
+After filing a report, a representative will contact you personally. If the person who is harassing you is part of the response team, they will recuse themselves from handling your incident. A representative will then review the incident, follow up with any additional questions, and make a decision as to how to respond. We will respect confidentiality requests for the purpose of protecting victims of abuse.
+
+Anyone asked to stop unacceptable behavior is expected to comply immediately. If an individual engages in unacceptable behavior, the representative may take any action they deem appropriate, up to and including a permanent ban from our community without warning.
+
+This Code Of Conduct follows the [template](https://github.com/todogroup/opencodeofconduct) established by the [TODO Group](http://todogroup.org/).