docs: update readme and upgrading guide

skyra-project · Jan 24, 2024 · 4a137ba · 4a137ba
1 parent 35d329a
commit 4a137ba
Show file tree

Hide file tree

Showing 6 changed files with 267 additions and 75 deletions.
diff --git a/README.md b/README.md
@@ -220,27 +220,30 @@ export class AppComponent {}
 
 ###### Live Demo
 
-<!-- TODO: Insert React Vite live demo -->
+[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/devbox/discord-components-vite-react-ts-cfqlyp)
+
+##### Sample code
+
+See [@skyra/discord-components-react](packages/react/README.md#sample-code)
 
 ##### Create React App
 
-###### Live Demo
+###### Important Notes
 
-[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/discord-components-create-react-app-64k90)
+Create React App is no longer the recommended way to start with a React app as
+per React's own documentation. We very strongly recommend using Vite instead.
 
 ##### NextJS
 
 ###### Important Notes
 
-When using this library with NextJS you _have_ to install the
-[@lit-labs/nextjs ](https://www.npmjs.com/package/@lit-labs/nextjs) package.
-Without this package your SSR rendering will fail! A stackblitz (provided by the
-Lit team) showing how to use this package can be found
-[here](https://stackblitz.com/edit/nextjs-lit-ssr?file=next.config.js)
-
-##### Live Demo
-
-[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/discord-components-nextjs-ovqfu)
+Support for NextJS can currently not be guaranteed. The package
+[@lit-labs/nextjs](https://www.npmjs.com/package/@lit-labs/nextjs) currently
+does [not support the app directory](https://github.com/lit/lit/issues/3657) and
+with the pages directory there are JSX rendering issues. We recommend following
+the GitHub issue linked above as well as Lit in general for progress with NextJS
+support. We will update this library if needed, but for now we cannot offer
+anything to add proper NextJS support.
 
 ##### Sample code
 
@@ -291,20 +294,16 @@ export default defineConfig({
 
 #### No Framework
 
-##### Live Demo
-
-[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/discord-components-static-nhwkl)
+##### Important Notes
 
-##### Sample Code
+Note that while it is entirely possible to use this library without a framework,
+you will still need a bundler such as [vite](https://vitejs.dev/). This is
+because this library exposes ES modules which need to be bundled into a format
+that the browser can support. The live demo below uses Vite.
 
-If you're want to use the browser build, you can pull it in via unpkg.
+##### Live Demo
 
-```html
-<script
-  type="module"
-  src="https://unpkg.com/@skyra/discord-components-core"
-></script>
-```
+[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/devbox/discord-components-no-framework-xnhqs8)
 
 <!-- # CORE_USAGE END # -->
 

diff --git a/assets/readme-templates/CORE_USAGE.md b/assets/readme-templates/CORE_USAGE.md
@@ -114,27 +114,30 @@ export class AppComponent {}
 
 ###### Live Demo
 
-<!-- TODO: Insert React Vite live demo -->
+[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/devbox/discord-components-vite-react-ts-cfqlyp)
+
+##### Sample code
+
+See [@skyra/discord-components-react](packages/react/README.md#sample-code)
 
 ##### Create React App
 
-###### Live Demo
+###### Important Notes
 
-[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/discord-components-create-react-app-64k90)
+Create React App is no longer the recommended way to start with a React app as
+per React's own documentation. We very strongly recommend using Vite instead.
 
 ##### NextJS
 
 ###### Important Notes
 
-When using this library with NextJS you _have_ to install the
-[@lit-labs/nextjs ](https://www.npmjs.com/package/@lit-labs/nextjs) package.
-Without this package your SSR rendering will fail! A stackblitz (provided by the
-Lit team) showing how to use this package can be found
-[here](https://stackblitz.com/edit/nextjs-lit-ssr?file=next.config.js)
-
-##### Live Demo
-
-[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/discord-components-nextjs-ovqfu)
+Support for NextJS can currently not be guaranteed. The package
+[@lit-labs/nextjs](https://www.npmjs.com/package/@lit-labs/nextjs) currently
+does [not support the app directory](https://github.com/lit/lit/issues/3657) and
+with the pages directory there are JSX rendering issues. We recommend following
+the GitHub issue linked above as well as Lit in general for progress with NextJS
+support. We will update this library if needed, but for now we cannot offer
+anything to add proper NextJS support.
 
 ##### Sample code
 
@@ -185,19 +188,15 @@ export default defineConfig({
 
 #### No Framework
 
-##### Live Demo
-
-[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/discord-components-static-nhwkl)
+##### Important Notes
 
-##### Sample Code
+Note that while it is entirely possible to use this library without a framework,
+you will still need a bundler such as [vite](https://vitejs.dev/). This is
+because this library exposes ES modules which need to be bundled into a format
+that the browser can support. The live demo below uses Vite.
 
-If you're want to use the browser build, you can pull it in via unpkg.
+##### Live Demo
 
-```html
-<script
-  type="module"
-  src="https://unpkg.com/@skyra/discord-components-core"
-></script>
-```
+[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/devbox/discord-components-no-framework-xnhqs8)
 
 <!-- # CORE_USAGE END # -->
diff --git a/package.json b/package.json
@@ -10,6 +10,7 @@
 		"lint": "eslint packages/ --fix --ext ts,tsx",
 		"prettier": "prettier --ignore-path=.prettierignore",
 		"format": "prettier --log-level=warn --write .",
+		"inject": "run-s \"inject-*\" && prettier --write --log-level=warn \"./**/README.md\" \"./**/package.json\"",
 		"inject-readme-markdown": "node scripts/inject-readme-markdown.mjs",
 		"inject-package-exports": "node scripts/update-exports-and-side-effects.mjs",
 		"inject-core-index-re-exports": "node scripts/update-core-index-exports.mjs",
@@ -41,6 +42,7 @@
 		"eslint-plugin-prettier": "^5.1.3",
 		"lint-staged": "^15.2.0",
 		"markdown-toc": "^1.2.0",
+		"npm-run-all": "^4.1.5",
 		"prettier": "^3.2.4",
 		"react": "^18.2.0",
 		"rimraf": "^5.0.5",

diff --git a/packages/core/README.md b/packages/core/README.md
@@ -228,27 +228,30 @@ export class AppComponent {}
 
 ###### Live Demo
 
-<!-- TODO: Insert React Vite live demo -->
+[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/devbox/discord-components-vite-react-ts-cfqlyp)
+
+##### Sample code
+
+See [@skyra/discord-components-react](packages/react/README.md#sample-code)
 
 ##### Create React App
 
-###### Live Demo
+###### Important Notes
 
-[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/discord-components-create-react-app-64k90)
+Create React App is no longer the recommended way to start with a React app as
+per React's own documentation. We very strongly recommend using Vite instead.
 
 ##### NextJS
 
 ###### Important Notes
 
-When using this library with NextJS you _have_ to install the
-[@lit-labs/nextjs ](https://www.npmjs.com/package/@lit-labs/nextjs) package.
-Without this package your SSR rendering will fail! A stackblitz (provided by the
-Lit team) showing how to use this package can be found
-[here](https://stackblitz.com/edit/nextjs-lit-ssr?file=next.config.js)
-
-##### Live Demo
-
-[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/discord-components-nextjs-ovqfu)
+Support for NextJS can currently not be guaranteed. The package
+[@lit-labs/nextjs](https://www.npmjs.com/package/@lit-labs/nextjs) currently
+does [not support the app directory](https://github.com/lit/lit/issues/3657) and
+with the pages directory there are JSX rendering issues. We recommend following
+the GitHub issue linked above as well as Lit in general for progress with NextJS
+support. We will update this library if needed, but for now we cannot offer
+anything to add proper NextJS support.
 
 ##### Sample code
 
@@ -299,20 +302,16 @@ export default defineConfig({
 
 #### No Framework
 
-##### Live Demo
-
-[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/discord-components-static-nhwkl)
+##### Important Notes
 
-##### Sample Code
+Note that while it is entirely possible to use this library without a framework,
+you will still need a bundler such as [vite](https://vitejs.dev/). This is
+because this library exposes ES modules which need to be bundled into a format
+that the browser can support. The live demo below uses Vite.
 
-If you're want to use the browser build, you can pull it in via unpkg.
+##### Live Demo
 
-```html
-<script
-  type="module"
-  src="https://unpkg.com/@skyra/discord-components-core"
-></script>
-```
+[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/devbox/discord-components-no-framework-xnhqs8)
 
 <!-- # CORE_USAGE END # -->
 

diff --git a/packages/core/UPGRADING-TO-V4.md b/packages/core/UPGRADING-TO-V4.md
@@ -70,4 +70,49 @@ import {
 } from '@skyra/discord-components-react';
 ```
 
+### Support for NextJS
+
+Support for NextJS can currently not be guaranteed. The package
+[@lit-labs/nextjs](https://www.npmjs.com/package/@lit-labs/nextjs) currently
+does [not support the app directory](https://github.com/lit/lit/issues/3657) and
+with the pages directory there are JSX rendering issues. We recommend following
+the GitHub issue linked above as well as Lit in general for progress with NextJS
+support. We will update this library if needed, but for now we cannot offer
+anything to add proper NextJS support.
+
+### Default font
+
+A while ago Discord changes their default font from "Whitney" to "gg sans". This
+library will load this font first if a `font-family` with name `gg sans` is
+found. You will need to provide this font yourself as it's a licensed font and
+we cannot distribute it.
+
+### Whitney font
+
+In version 3 this library would automatically load the Whitney font from our
+CDN. Starting version 4 this will no longer happen automatically as we had
+reports of our CDN causing slow downs for users in distant regions compared to
+where our CDN was hosted. If you want to use the Whitney font you will need to
+provide it yourself. An example for this can be found in the
+[README](./README.md#using-the-discord-font).
+
+### Frameworkless usage
+
+It is no longer possible to use this library simply by importing the unpkg URL.
+You have to use a bundler such as [Vite](https://vitejs.dev) or
+[Webpack](https://webpack.js.org) to use this library.
+
+### Component changes
+
+#### `discord-inline-code`
+
+The `discord-inline-code` component has been removed in favour of a property on
+`discord-code`. To get inline code you now simply use `discord-code` which will
+default to inline.
+
+#### `discord-code`
+
+As mentioned above, `discord-code` will default to inline. To get multiline code
+blocks set `multiline="true"` as property.
+
 [Lit]: https://lit.dev