diff --git a/docs/admin/bundlers.mdx b/docs/admin/bundlers.mdx index e69de29bb2..a5af403610 100644 --- a/docs/admin/bundlers.mdx +++ b/docs/admin/bundlers.mdx @@ -0,0 +1,6 @@ +--- +title: Bundlers +label: Bundlers +order: 60 +desc: NEEDS TO BE WRITTEN +--- \ No newline at end of file diff --git a/docs/admin/environment-vars.mdx b/docs/admin/environment-vars.mdx new file mode 100644 index 0000000000..6ccbd37d79 --- /dev/null +++ b/docs/admin/environment-vars.mdx @@ -0,0 +1,28 @@ +--- +title: Environment Variables in Admin UI +label: Environment Variables +order: 100 +desc: NEEDS TO BE WRITTEN +--- + +TODO: expand on this and make sure it looks nice, talk about how if you use a `process.env.SERVER_URL`, it might not be usable in your Payload config in your admin UI, but it needs to be, so it should be prefixed like `process.env.PAYLOAD_PUBLIC_SERVER_URL` to work in both places + +## Admin environment vars + + + Important: +
+ Be careful about what variables you provide to your client-side code. Analyze every single one to + make sure that you're not accidentally leaking anything that an attacker could exploit. Only keys + that are safe to be available to everyone in plain text should be provided to your Admin panel. + + +By default, `env` variables are **not** provided to the Admin panel for security and safety reasons. But, Payload provides you with a way to still provide `env` vars to your frontend code. + +**Payload will automatically supply any present `env` variables that are prefixed with `PAYLOAD_PUBLIC_` directly to the Admin panel.** + +For example, if you've got the following environment variable: + +`PAYLOAD_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_XXXXXXXXXXXXXXXXXX` + +This key will automatically be made available to the Payload bundle and can be referenced in your Admin component code as `process.env.PAYLOAD_PUBLIC_STRIPE_PUBLISHABLE_KEY`. diff --git a/docs/admin/excluding-server-code.mdx b/docs/admin/excluding-server-code.mdx new file mode 100644 index 0000000000..1142d5b910 --- /dev/null +++ b/docs/admin/excluding-server-code.mdx @@ -0,0 +1,9 @@ +--- +title: Excluding server-only code from admin UI +label: Excluding server code +order: 70 +desc: NEEDS TO BE WRITTEN +--- + +- Talk about the theory behind using aliases to exclude files +- Talk about environment variables maybe? \ No newline at end of file diff --git a/docs/admin/overview.mdx b/docs/admin/overview.mdx index 420d9ee74a..faefb6c5f4 100644 --- a/docs/admin/overview.mdx +++ b/docs/admin/overview.mdx @@ -8,6 +8,7 @@ keywords: admin, components, custom, customize, documentation, Content Managemen Payload dynamically generates a beautiful, fully functional React admin panel to manage your data. It's extremely powerful and can be customized / extended upon easily by swapping in your own React components. You can add additional views, modify how built-in views look / work, swap out Payload branding for your client's, build your own field types and much more. +TODO: change the sentence below to reference our adapter pattern, and officially supported bundlers, linking to Vite and Webpack docs pages specifically The Payload Admin panel is built with Webpack, code-split, highly performant (even with 100+ fields), and written fully in TypeScript. @@ -24,6 +25,8 @@ _Screenshot of the Admin panel while editing a document from an example `AllFiel All options for the Admin panel are defined in your base Payload config file. +TODO: add `vite` and `bundler` properties to the table below + | Option | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `user` | The `slug` of a Collection that you want be used to log in to the Admin dashboard. [More](/docs/admin/overview#the-admin-user-collection) | diff --git a/docs/admin/vite.mdx b/docs/admin/vite.mdx new file mode 100644 index 0000000000..1b6564a61b --- /dev/null +++ b/docs/admin/vite.mdx @@ -0,0 +1,15 @@ +--- +title: Vite +label: Vite +order: 90 +desc: NEEDS TO BE WRITTEN +--- + +- Show how to install official bundler +- Give banner "warning" that this is in beta +- Talk about how you should see performance improvements in both build times and HMR +- Initial load might not be substantially faster, because Vite pre-bundles dependencies +- Talk about the new `admin.vite` property +- Talk about how for compatibility, the Vite config still automatically adds aliases that come in from the `admin.webpack` property + +- Aliases work differently in Vite vs. Webpack (you can't pass Vite an absolute path to your alias source, it needs to match perfectly) diff --git a/docs/admin/webpack.mdx b/docs/admin/webpack.mdx index 5e87c4f289..816bd76f91 100644 --- a/docs/admin/webpack.mdx +++ b/docs/admin/webpack.mdx @@ -1,11 +1,15 @@ --- title: Webpack label: Webpack -order: 60 +order: 80 desc: The Payload admin panel uses Webpack 5 and supports many common functionalities such as SCSS and Typescript out of the box to give you more freedom. keywords: admin, webpack, documentation, Content Management System, cms, headless, javascript, node, react, express --- +TODO: rewrite this +- Talk about how Webpack is stable, and should be used unless you are adventurous. +- Show a code example about how to install and pass the Webpack bundler to the Payload config + Payload uses Webpack 5 to build the Admin panel. It comes with support for many common functionalities such as SCSS and Typescript out of the box, but there are many cases where you may need to add support for additional functionalities. To extend the Webpack config, add the `webpack` key to your base Payload config, and provide a function that accepts the default Webpack config as its only argument: @@ -28,6 +32,10 @@ export default buildConfig({ }) ``` +TODO: move the aliasing section to its own page +- Talk about how Webpack is stable, and should be used unless you are adventurous. +- Show a code example about how to install and pass the Webpack bundler to the Payload config + ### Aliasing server-only modules A common use case for extending the Payload config is to alias server-only modules, thus preventing them from inclusion into the browser JavaScript bundle. @@ -175,23 +183,3 @@ Now, when Webpack sees that you're attempting to import your `createStripeSubscr [cached](https://webpack.js.org/configuration/cache/) in `node_modules/.cache/webpack`. Try deleting that folder and restarting your server. - -## Admin environment vars - - - Important: -
- Be careful about what variables you provide to your client-side code. Analyze every single one to - make sure that you're not accidentally leaking anything that an attacker could exploit. Only keys - that are safe to be available to everyone in plain text should be provided to your Admin panel. - - -By default, `env` variables are **not** provided to the Admin panel for security and safety reasons. But, Payload provides you with a way to still provide `env` vars to your frontend code. - -**Payload will automatically supply any present `env` variables that are prefixed with `PAYLOAD_PUBLIC_` directly to the Admin panel.** - -For example, if you've got the following environment variable: - -`PAYLOAD_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_XXXXXXXXXXXXXXXXXX` - -This key will automatically be made available to the Payload bundle and can be referenced in your Admin component code as `process.env.PAYLOAD_PUBLIC_STRIPE_PUBLISHABLE_KEY`. diff --git a/docs/database/migrations.mdx b/docs/database/migrations.mdx new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/database/transactions.mdx b/docs/database/transactions.mdx new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/live-preview/frontend.mdx b/docs/live-preview/frontend.mdx new file mode 100644 index 0000000000..db231a5019 --- /dev/null +++ b/docs/live-preview/frontend.mdx @@ -0,0 +1,13 @@ +--- +title: Implementing Live Preview in your app +label: Frontend Implementation +order: 20 +desc: NEED TO WRITE +keywords: NEED TO WRITE +--- + +- Talk about in detail how it works on the frontend +- How you should write your frontend to be "safe" and not break if there is no data filled in a required field, etc. +- Your UI should be reactive to new props +- Loading states +- Etc. \ No newline at end of file diff --git a/docs/live-preview/overview.mdx b/docs/live-preview/overview.mdx new file mode 100644 index 0000000000..4d6e7acf04 --- /dev/null +++ b/docs/live-preview/overview.mdx @@ -0,0 +1,13 @@ +--- +title: Live Preview +label: Overview +order: 10 +desc: NEED TO WRITE +keywords: NEED TO WRITE +--- + +TODO: write docs here +- Show screenshot of the usage +- Talk about how it works at a high level +- Talk about the property on `collectionConfig.admin` +- Talk about the React hook, and the subsequent package that it relies on which can be used for other frameworks diff --git a/docs/plugins/admin-compatibility.mdx b/docs/plugins/admin-compatibility.mdx new file mode 100644 index 0000000000..3b9dbab866 --- /dev/null +++ b/docs/plugins/admin-compatibility.mdx @@ -0,0 +1,10 @@ +--- +title: Admin panel compatibility +label: Admin compatibility +order: 20 +desc: NEEDS TO BE WRITTEN +--- + +TODO: talk about how plugins need to ensure compatibility with both Vite and Webpack + +- It's best practice to alias your plugin to an admin-only version, so if you have admin-only changes, put them in the admin plugin, and then leave the full plugin, complete with server code, to be installed on the server side \ No newline at end of file diff --git a/docs/rich-text/frontend.mdx b/docs/rich-text/frontend.mdx new file mode 100644 index 0000000000..1d4923f83d --- /dev/null +++ b/docs/rich-text/frontend.mdx @@ -0,0 +1,10 @@ +--- +title: Rendering Rich Text on your Frontend +label: Rendering on Frontend +order: 20 +desc: NEED TO WRITE +keywords: NEED TO WRITE +--- + +Give an example for how to render JSX on the frontend +In the future, we will add docs that show how to add virtual fields for HTML / MDX transforming \ No newline at end of file diff --git a/docs/rich-text/lexical.mdx b/docs/rich-text/lexical.mdx new file mode 100644 index 0000000000..b3b4a11bb3 --- /dev/null +++ b/docs/rich-text/lexical.mdx @@ -0,0 +1,11 @@ +--- +title: Lexical Rich Text +label: Lexical +order: 30 +desc: NEED TO WRITE +keywords: NEED TO WRITE +--- + +Talk about the reasons why we are using Lexical, what it does well, and where we plan to go in the future +Show a code snippet for how to install it +Show how to configure it, with options \ No newline at end of file diff --git a/docs/rich-text/overview.mdx b/docs/rich-text/overview.mdx new file mode 100644 index 0000000000..173eb7f825 --- /dev/null +++ b/docs/rich-text/overview.mdx @@ -0,0 +1,16 @@ +--- +title: Overview +label: Rich Text Field +order: 10 +desc: NEED TO WRITE +keywords: NEED TO WRITE +--- + +TODO: + +- Talk about how Payload supports two rich text editors, and they work on an "adapter" pattern, which means you need to install the one you want to use separately and pass it to config +- Talk about how Slate is still supported for legacy projects, but we are moving to Lexical from here on out which offers more features +- For new projects as of 2.0, use Lexical +- For existing projects, use Slate +- Probably move some of the more complex docs from Fields -> Rich Text over to this set of docs +- Show how you can install an editor at the top level, or override on a field-by-field basis (not recommended, no reason to have 2 editors installed. Lots of JS loaded) \ No newline at end of file diff --git a/docs/rich-text/slate.mdx b/docs/rich-text/slate.mdx new file mode 100644 index 0000000000..3e83be014a --- /dev/null +++ b/docs/rich-text/slate.mdx @@ -0,0 +1,9 @@ +--- +title: Slate Rich Text +label: Slate +order: 40 +desc: NEED TO WRITE +keywords: NEED TO WRITE +--- + +Recreate a similar approach to Lexical here \ No newline at end of file