tabshift/payloadcms
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

fix: strict custom view paths (#12968)

Browse Source
This commit is contained in:
Jacob Fletcher
2025-06-29 14:20:54 -04:00
committed by GitHub
parent 16f5538e12
commit cfc7adcbc5
5 changed files with 81 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
docs/admin/overview.mdx
View File

@@ -32,18 +32,18 @@ The Admin Panel serves as the entire HTTP layer for Payload, providing a full CR
Once you [install Payload](../getting-started/installation), the following files and directories will be created in your app:
```plaintext
app/
├─ (payload)/
├── admin/
├─── [[...segments]]/
app
├─ (payload)
├── admin
├─── [[...segments]]
├──── page.tsx
├──── not-found.tsx
├── api/
├─── [...slug]/
├── api
├─── [...slug]
├──── route.ts
├── graphql/
├── graphql
├──── route.ts
├── graphql-playground/
├── graphql-playground
├──── route.ts
├── custom.scss
├── layout.tsx
@@ -84,29 +84,30 @@ import { buildConfig } from 'payload'
const config = buildConfig({
// ...
// highlight-start
admin: {
// highlight-line
// ...
},
// highlight-end
})
```
The following options are available:
| Option | Description |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **`avatar`** | Set account profile picture. Options: `gravatar`, `default` or a custom React component. |
| **`autoLogin`** | Used to automate log-in for dev and demonstration convenience. [More details](../authentication/overview). |
| **`components`** | Component overrides that affect the entirety of the Admin Panel. [More details](../custom-components/overview). |
| **`custom`** | Any custom properties you wish to pass to the Admin Panel. |
| **`dateFormat`** | The date format that will be used for all dates within the Admin Panel. Any valid [date-fns](https://date-fns.org/) format pattern can be used. |
| **`livePreview`** | Enable real-time editing for instant visual feedback of your front-end application. [More details](../live-preview/overview). |
| **`meta`** | Base metadata to use for the Admin Panel. [More details](./metadata). |
| **`routes`** | Replace built-in Admin Panel routes with your own custom routes. [More details](#customizing-routes). |
| **`suppressHydrationWarning`** | If set to `true`, suppresses React hydration mismatch warnings during the hydration of the root `<html>` tag. Defaults to `false`. |
| **`theme`** | Restrict the Admin Panel theme to use only one of your choice. Default is `all`. |
| **`timezones`** | Configure the timezone settings for the admin panel. [More details](#timezones) |
| **`user`** | The `slug` of the Collection that you want to allow to login to the Admin Panel. [More details](#the-admin-user-collection). |
| Option | Description |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `avatar` | Set account profile picture. Options: `gravatar`, `default` or a custom React component. |
| `autoLogin` | Used to automate log-in for dev and demonstration convenience. [More details](../authentication/overview). |
| `components` | Component overrides that affect the entirety of the Admin Panel. [More details](../custom-components/overview). |
| `custom` | Any custom properties you wish to pass to the Admin Panel. |
| `dateFormat` | The date format that will be used for all dates within the Admin Panel. Any valid [date-fns](https://date-fns.org/) format pattern can be used. |
| `livePreview` | Enable real-time editing for instant visual feedback of your front-end application. [More details](../live-preview/overview). |
| `meta` | Base metadata to use for the Admin Panel. [More details](./metadata). |
| `routes` | Replace built-in Admin Panel routes with your own custom routes. [More details](#customizing-routes). |
| `suppressHydrationWarning` | If set to `true`, suppresses React hydration mismatch warnings during the hydration of the root `<html>` tag. Defaults to `false`. |
| `theme` | Restrict the Admin Panel theme to use only one of your choice. Default is `all`. |
| `timezones` | Configure the timezone settings for the admin panel. [More details](#timezones) |
| `user` | The `slug` of the Collection that you want to allow to login to the Admin Panel. [More details](#the-admin-user-collection). |
<Banner type="success">
**Reminder:** These are the _root-level_ options for the Admin Panel. You can
@@ -186,6 +187,12 @@ The following options are available:
| `graphQL` | `/graphql` | The [GraphQL API](../graphql/overview) base path. |
| `graphQLPlayground` | `/graphql-playground` | The GraphQL Playground. |
<Banner type="warning">
**Important:** Changing Root-level Routes also requires a change to [Project
Structure](#project-structure) to match the new route. [More
details](#customizing-root-level-routes).
</Banner>
<Banner type="success">
**Tip:** You can easily add _new_ routes to the Admin Panel through [Custom
Endpoints](../rest-api/overview#custom-endpoints) and [Custom
@@ -196,13 +203,29 @@ The following options are available:
You can change the Root-level Routes as needed, such as to mount the Admin Panel at the root of your application.
Changing Root-level Routes also requires a change to [Project Structure](#project-structure) to match the new route. For example, if you set `routes.admin` to `/`, you would need to completely remove the `admin` directory from the project structure:
This change, however, also requires a change to your [Project Structure](#project-structure) to match the new route.
For example, if you set `routes.admin` to `/`:
```ts
import { buildConfig } from 'payload'
const config = buildConfig({
// ...
routes: {
admin: '/', // highlight-line
},
})
```
Then you would need to completely remove the `admin` directory from the project structure:
```plaintext
app/
├─ (payload)/
├── [[...segments]]/
app
├─ (payload)
├── [[...segments]]
├──── ...
├── layout.tsx
```
<Banner type="warning">

2
docs/custom-components/custom-views.mdx
View File

@@ -51,7 +51,7 @@ For more granular control, pass a configuration object instead. Payload exposes
| Property | Description |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Component` \* | Pass in the component path that should be rendered when a user navigates to this route. |
| `path` \* | Any valid URL path or array of paths that [`path-to-regexp`](https://www.npmjs.com/package/path-to-regex) understands. |
| `path` \* | Any valid URL path or array of paths that [`path-to-regexp`](https://www.npmjs.com/package/path-to-regex) understands. Must begin with a forward slash (`/`). |
| `exact` | Boolean. When true, will only match if the path matches the `usePathname()` exactly. |
| `strict` | When true, a path that has a trailing slash will only match a `location.pathname` with a trailing slash. This has no effect when there are additional URL segments in the pathname. |
| `sensitive` | When true, will match if the path is case sensitive. |

5
packages/payload/src/admin/views/index.ts
View File

@@ -23,7 +23,10 @@ export type AdminViewConfig = {
/** Whether the path should be matched exactly or as a prefix */
exact?: boolean
meta?: MetaConfig
path?: string
/**
* Any valid URL path or array of paths that [`path-to-regexp`](https://www.npmjs.com/package/path-to-regex) understands. Must begin with a forward slash (`/`).
*/
path?: `/${string}`
sensitive?: boolean
strict?: boolean
}

31
packages/payload/src/config/types.ts
View File

@@ -375,7 +375,7 @@ type BaseDocumentViewConfig = {
export type CustomDocumentViewConfig =
| ({
Component: DocumentViewComponent
path: string
path: `/${string}`
} & BaseDocumentViewConfig)
| ({
Component?: DocumentViewComponent
@@ -1162,18 +1162,35 @@ export type Config = {
filterConstraints?: SelectField['filterOptions']
labels?: CollectionConfig['labels']
}
/** Control the routing structure that Payload binds itself to. */
/**
* Control the routing structure that Payload binds itself to.
* @link https://payloadcms.com/docs/admin/overview#root-level-routes
*/
routes?: {
/** The route for the admin panel.
* @example "/my-admin"
/**
* The route for the admin panel.
* @example "/my-admin" or "/"
* @default "/admin"
* @link https://payloadcms.com/docs/admin/overview#root-level-routes
*/
admin?: string
/** @default "/api" */
/**
* The base route for all REST API endpoints.
* @default "/api"
* @link https://payloadcms.com/docs/admin/overview#root-level-routes
*/
api?: string
/** @default "/graphql" */
/**
* The base route for all GraphQL endpoints.
* @default "/graphql"
* @link https://payloadcms.com/docs/admin/overview#root-level-routes
*/
graphQL?: string
/** @default "/graphql-playground" */
/**
* The route for the GraphQL Playground.
* @default "/graphql-playground"
* @link https://payloadcms.com/docs/admin/overview#root-level-routes
*/
graphQLPlayground?: string
}
/** Secure string that Payload will use for any encryption workflows */

4
test/types/types.spec.ts
View File

@@ -164,12 +164,12 @@ describe('Types testing', () => {
describe('views', () => {
test('default view config', () => {
expect<DefaultDocumentViewConfig>().type.not.toBeAssignableWith<{
path: string
path: `/${string}`
}>()
expect<CustomDocumentViewConfig>().type.toBeAssignableWith<{
Component: string
path: string
path: `/${string}`
}>()
})
})