diff --git a/docusaurus/docs/cms/admin-panel-customization.md b/docusaurus/docs/cms/admin-panel-customization.md index a21e72e0f5..614c7a9a19 100644 --- a/docusaurus/docs/cms/admin-panel-customization.md +++ b/docusaurus/docs/cms/admin-panel-customization.md @@ -7,24 +7,207 @@ tags: - admin panel customization --- +import HotReloading from '/docs/snippets/hot-reloading-admin-panel.md' + # Admin panel customization -The front-end part of Strapi is called the admin panel. The admin panel presents a graphical user interface to help you structure and manage the content that will be accessible through the Content API. The admin panel is a React-based single-page application that encapsulates all the features and installed plugins of a Strapi application. +The **front-end part of Strapi** For a clarification on the distinction between: refer to the [development introduction](/cms/customization). is called the admin panel. The admin panel presents a graphical user interface to help you structure and manage the content that will be accessible through the Content API. To get an overview of the admin panel, please refer to the [Getting Started > Admin panel](/cms/features/admin-panel) page. + +From a developer point of view, Strapi's admin panel is a React-based single-page application that encapsulates all the features and installed plugins of a Strapi application. + +Admin panel customization is done by tweaking the code of the `src/admin/app` fileor other files included in the `src/admin` folder (see [project structure](/cms/project-structure)). By doing so, you can: + +- Customize some parts of the admin panel to better reflect your brand identity (logos, favicon) or your language, +- Replace some other parts of the admin panel, such as the Rich text editor and the bundler, +- Extend the theme or the admin panel to add new features or customize the existing user interface. + +## General considerations + +:::prerequisites +Before updating code to customize the admin panel: + +- Rename the default `app.example.tsx|js` file into `app.ts|js`. +- Create a new `extensions` folder in `/src/admin/`. +- If you want to see your changes applied live while developing, ensure the admin panel server is running (it's usually done with the `yarn develop` or `npm run develop` command if you have not changed the default [host, port, and path](/cms/configurations/admin-panel#admin-panel-server) of the admin panel). +::: + +Most basic admin panel customizations will be done in the `/src/admin/app` file, which includes a `config` object. + +Any file used by the `config` object (e.g., a custom logo) should be placed in a `/src/admin/extensions/` folder and imported inside `/src/admin/app.js`. + +:::note Note: Admin panel extensions vs. plugins extensions +By default, Strapi projects already contain another `extensions` folder in `/src` but it is for plugins extensions only (see [Plugins extension](/cms/plugins-development/plugins-extension)). +::: + + + +## Available customizations + +The `config` object of `/src/admin/app` accepts the following parameters: + +| Parameter | Type | Description | +| ------------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------- | +| `auth` | Object | Accepts a `logo` key to replace the default Strapi logo on login screen | +| `head` | Object | Accepts a `favicon` key to replace the default Strapi favicon | +| `locales` | Array of Strings | Defines availables locales | +| `translations` | Object | Extends the translations | +| `menu` | Object | Accepts the `logo` key to change the logo in the main navigation | +| `theme.light` and `theme.dark` | Object | Overwrite theme properties for light and dark modes | +| `tutorials` | Boolean | Toggles displaying the video tutorials +| `notifications` | Object | Accepts the `releases` key (Boolean) to toggle displaying notifications about new releases | + +Click on any of the following cards to get more details about a specific topic: + + + + + + + + + + + +## Basic example + +The following is an example of a basic customization of the admin panel: + + + + +```jsx title="/src/admin/app.js" +import AuthLogo from "./extensions/my-logo.png"; +import MenuLogo from "./extensions/logo.png"; +import favicon from "./extensions/favicon.png"; + +export default { + config: { + // Replace the Strapi logo in auth (login) views + auth: { + logo: AuthLogo, + }, + // Replace the favicon + head: { + favicon: favicon, + }, + // Add a new locale, other than 'en' + locales: ["fr", "de"], + // Replace the Strapi logo in the main navigation + menu: { + logo: MenuLogo, + }, + // Override or extend the theme + theme: { + // overwrite light theme properties + light: { + colors: { + primary100: "#f6ecfc", + primary200: "#e0c1f4", + primary500: "#ac73e6", + primary600: "#9736e8", + primary700: "#8312d1", + danger700: "#b72b1a", + }, + }, + + // overwrite dark theme properties + dark: { + // ... + }, + }, + // Extend the translations + translations: { + fr: { + "Auth.form.email.label": "test", + Users: "Utilisateurs", + City: "CITY (FRENCH)", + // Customize the label of the Content Manager table. + Id: "ID french", + }, + }, + // Disable video tutorials + tutorials: false, + // Disable notifications about new Strapi releases + notifications: { releases: false }, + }, + + bootstrap() {}, +}; +``` + + + + + +```jsx title="/src/admin/app.ts" +// Note: you may see some ts errors, don't worry about them +import AuthLogo from "./extensions/my-logo.png"; +import MenuLogo from "./extensions/logo.png"; +import favicon from "./extensions/favicon.png"; + +export default { + config: { + // Replace the Strapi logo in auth (login) views + auth: { + logo: AuthLogo, + }, + // Replace the favicon + head: { + // Try to change the origin favicon.png file in the + // root of strapi project if this config don't work. + favicon: favicon, + }, + // Add a new locale, other than 'en' + locales: ["fr", "de"], + // Replace the Strapi logo in the main navigation + menu: { + logo: MenuLogo, + }, + // Override or extend the theme + theme: { + dark:{ + colors: { + alternative100: '#f6ecfc', + alternative200: '#e0c1f4', + alternative500: '#ac73e6', + alternative600: '#9736e8', + alternative700: '#8312d1', + buttonNeutral0: '#ffffff', + buttonPrimary500: '#7b79ff', + // you can see other colors in the link below + }, + }, + light:{ + // you can see the light color here just like dark colors https://github.com/strapi/design-system/blob/main/packages/design-system/src/themes/lightTheme/light-colors.ts + }, + }, + }, + // Extend the translations + // you can see the traslations keys here https://github.com/strapi/strapi/blob/develop/packages/core/admin/admin/src/translations + translations: { + fr: { + "Auth.form.email.label": "test", + Users: "Utilisateurs", + City: "CITY (FRENCH)", + // Customize the label of the Content Manager table. + Id: "ID french", + }, + }, + // Disable video tutorials + tutorials: false, + // Disable notifications about new Strapi releases + notifications: { releases: false }, + }, -Admin panel customization is a broad topic in Strapi and covers the following aspects: + bootstrap() {}, +}; +``` -- Some parts of the admin panel can be customized to better reflect your brand identity or to modify some default Strapi behaviors. -- Some other parts of the admin panel, such as the WYSIWYG editor and the bundler, can be replaced. -- The admin panel can also be extended to add new features or customize the existing user interface. + + -Depending on what you want to achieve, you might need to update different parts of Strapi, as summarized in the following table: +:::strapi Detailed examples in the codebase -| Customization use case | How to customize it | Related documentation | -|---------------------------|-----------------------|-----------------------| -| Update the admin panel's host, port, and path | By updating the code of the config/admin.ts|js file | [ Host, port, and path configuration](/cms/admin-panel-customization/host-port-path) | -| | By updating the code of the src/admin/app.ts|js file | [Customization options](/cms/admin-panel-customization/options) | -| Choose and configure a bundler | By writing some code in dedicated configuration files found in the `src/admin` folder | [Bundlers](/cms/admin-panel-customization/bundlers) | -| Replace or customize the WYSIWYG editor | _(Various strategies available, see related documentation)_ | [WYSIWYG editor](/cms/admin-panel-customization/wysiwyg-editor) | -| Extend the admin panel | _(Various strategies available, see related documentation)_ | [Extension](/cms/admin-panel-customization/extension) | -| Deploy the admin panel | _(Various strategies available, see related documentation)_ | [Deployment](/cms/admin-panel-customization/deployment) | -| Customize the email templates | Directly from the admin panel through the settings for the Users & Permissions plugin | [User Guide for the Users & Permissions plugin](/cms/features/users-permissions#templating-emails) | +* You can see the full translation keys, for instance to change the welcome message, [on GitHub](https://github.com/strapi/strapi/blob/develop/packages/core/admin/admin/src/translations). +* Light and dark colors are also found [on GitHub](https://github.com/strapi/design-system/tree/main/packages/design-system/src/themes). +::: \ No newline at end of file diff --git a/docusaurus/docs/cms/admin-panel-customization/bundlers.md b/docusaurus/docs/cms/admin-panel-customization/bundlers.md index c2ed025330..37d8d599ce 100644 --- a/docusaurus/docs/cms/admin-panel-customization/bundlers.md +++ b/docusaurus/docs/cms/admin-panel-customization/bundlers.md @@ -23,7 +23,7 @@ For simplification, the following documentation mentions the `strapi develop` co In Strapi 5, is the default bundler that Strapi uses to build the admin panel. Vite will therefore be used by default when you run the `strapi develop` command. -To extend the usage of Vite, define a function that extends its configuration inside `/src/admin/vite.config.[js|ts]`: +To extend the usage of Vite, define a function that extends its configuration inside `/src/admin/vite.config`: @@ -74,10 +74,10 @@ strapi develop --bundler=webpack ``` :::prerequisites -Make sure to rename the default `webpack.config.example.js` file into `webpack.config.[js|ts]` before customizing webpack. +Make sure to rename the default `webpack.config.example.js` file into `webpack.config.` before customizing webpack. ::: -In order to extend the usage of webpack v5, define a function that extends its configuration inside `/src/admin/webpack.config.[js|ts]`: +In order to extend the usage of webpack v5, define a function that extends its configuration inside `/src/admin/webpack.config.`: diff --git a/docusaurus/docs/cms/admin-panel-customization/deployment.md b/docusaurus/docs/cms/admin-panel-customization/deployment.md deleted file mode 100644 index 9273e07d6d..0000000000 --- a/docusaurus/docs/cms/admin-panel-customization/deployment.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Admin panel deployment -description: Learn more about deploying Strapi's admin panel in various scenarios. -displayed_sidebar: cmsSidebar -sidebar_label: Deployment -toc_max_heading_level: 4 -tags: -- admin panel -- admin panel customization -- deployment ---- - -# Admin panel deployment - -The front-end part of Strapi is called the admin panel. The admin panel presents a graphical user interface to help you structure and manage the content that will be accessible to your application's own front-end through Strapi's Content API. - -The admin panel is a React-based single-page application that encapsulates all the features and installed plugins of a Strapi application. - -The [back-end server](/cms/backend-customization) of Strapi serves the Content API which provides endpoints to your content. - -By default, the back-end server and the admin panel server are deployed on the same server. But the admin panel and the back-end server are independent and can be deployed on different servers, which brings us to different scenarios: - -- Deploy the entire project on the same server. -- Deploy the administration panel on a server (AWS S3, Azure, etc) different from the API server. - -Build configurations differ for each case. - -Before deployment, the admin panel needs to be built, by running the following command from the project's root directory: - - - - - -```sh -yarn build -``` - - - - - -```sh -npm run build -``` - - - - - -This will replace the folder's content located at `./build`. Visit to make sure customizations have been taken into account. - -## Same server - -Deploying the admin panel and the back end (API) of Strapi on the same server is the default behavior. The build configuration will be automatically set. The server will start on the defined port and the administration panel will be accessible through `http://yourdomain.com:1337/admin`. - -:::tip -You might want to [change the path to access the administration panel](/cms/admin-panel-customization/host-port-path). -::: - -## Different servers - -To deploy the admin panel and the back end (API) of Strapi on different servers, use the following configuration: - - - - -```js title="./config/server.js" -module.exports = ({ env }) => ({ - host: env("HOST", "0.0.0.0"), - port: env.int("PORT", 1337), - url: "http://yourbackend.com", -}); -``` - -```js title="./config/admin.js" -module.exports = ({ env }) => ({ - /** - * Note: The administration will be accessible from the root of the domain - * (ex: http://yourfrontend.com/) - */ - url: "/", - serveAdminPanel: false, // http://yourbackend.com will not serve any static admin files -}); -``` - - - - - -```js title="./config/server.ts" -export default ({ env }) => ({ - host: env("HOST", "0.0.0.0"), - port: env.int("PORT", 1337), - url: "http://yourbackend.com", -}); -``` - -```js title="./config/admin.ts" -export default ({ env }) => ({ - /** - * Note: The administration will be accessible from the root of the domain - * (ex: http://yourfrontend.com/) - */ - url: "/", - serveAdminPanel: false, // http://yourbackend.com will not serve any static admin files -}); -``` - - - - -After running `yarn build` with this configuration, the `build` folder will be created/overwritten. Use this folder to serve it from another server with the domain of your choice (e.g. `http://yourfrontend.com`). - -The administration URL will then be `http://yourfrontend.com` and every request from the panel will hit the backend at `http://yourbackend.com`. - -:::note -If you add a path to the `url` option, it won't prefix your application. To do so, use a proxy server like Nginx (see [optional software deployment guides](/cms/deployment#additional-resources)). -::: diff --git a/docusaurus/docs/cms/admin-panel-customization/extension.md b/docusaurus/docs/cms/admin-panel-customization/extension.md index 60ae7d42db..a2d0aff342 100644 --- a/docusaurus/docs/cms/admin-panel-customization/extension.md +++ b/docusaurus/docs/cms/admin-panel-customization/extension.md @@ -2,7 +2,6 @@ title: Admin panel extension description: Learn more about extending Strapi's admin panel. displayed_sidebar: cmsSidebar -sidebar_label: Extension toc_max_heading_level: 4 tags: - admin panel @@ -14,7 +13,7 @@ import HotReloading from '/docs/snippets/hot-reloading-admin-panel.md' # Admin panel extension -Strapi's admin panel is a React-based single-page application that encapsulates all the features and installed plugins of a Strapi application. If the [customization options](/cms/admin-panel-customization/options) provided by Strapi are not enough for your use case, you will need to extend Strapi's admin panel. +Strapi's [admin panel](/cms/admin-panel-customization) is a React-based single-page application that encapsulates all the features and installed plugins of a Strapi application. If the [customization options](/cms/admin-panel-customization/options) provided by Strapi are not enough for your use case, you will need to extend Strapi's admin panel. Extending Strapi's admin panel means leveraging its React foundation to adapt and enhance the interface and features according to the specific needs of your project, which might imply creating new components or adding new types of fields. @@ -26,11 +25,11 @@ There are 2 use cases where you might want to extend the admin panel: - As a Strapi developer, you want to develop a unique solution for a Strapi user who only needs to extend a specific instance of a Strapi application. - 👉 This can be done by directly updating the `/src/admin/app.[tsx|js]` file, which can import any file located in `/src/admin/extensions`. + 👉 This can be done by directly updating the `/src/admin/app` file, which can import any file located in `/src/admin/extensions`. :::strapi Additional resources -* If you're searching for ways of replacing the default WYSIWYG editor, please refer to the [corresponding page](/cms/admin-panel-customization/wysiwyg-editor). -* The will also provide additional information on developing for Strapi's admin panel. +* If you're searching for ways of replacing the default Rich text editor, please refer to the [corresponding page](/cms/admin-panel-customization/wysiwyg-editor). +* The also provide extensive additional information on developing for Strapi's admin panel. ::: diff --git a/docusaurus/docs/cms/admin-panel-customization/favicon.md b/docusaurus/docs/cms/admin-panel-customization/favicon.md new file mode 100644 index 0000000000..8b728061d0 --- /dev/null +++ b/docusaurus/docs/cms/admin-panel-customization/favicon.md @@ -0,0 +1,43 @@ +--- +title: Favicon +description: Replace the favicon displayed in Strapi's admin panel. +displayed_sidebar: cmsSidebar +sidebar_label: Favicon +toc_max_heading_level: 4 +tags: +- admin panel +- admin panel customization +--- + +# Favicon + +To replace the favicon: + +1. Create a `/src/admin/extensions/` folder if the folder does not already exist. +2. Upload your favicon into `/src/admin/extensions/`. +3. Replace the existing **favicon.png|ico** file at the Strapi application root with a custom `favicon.png|ico` file. +4. Update `/src/admin/app.[tsx|js]` with the following: + + ```js title="./src/admin/app.js" + import favicon from "./extensions/favicon.png"; + + export default { + config: { + // replace favicon with a custom icon + head: { + favicon: favicon, + }, + }, + }; + ``` + +5. Rebuild, launch and revisit your Strapi app by running `yarn build && yarn develop` in the terminal. + +:::tip +This same process may be used to replace the login logo (i.e. `AuthLogo`) and menu logo (i.e. `MenuLogo`) (see [logos customization documentation](/cms/admin-panel-customization/logos)). +::: + +:::caution +Make sure that the cached favicon is cleared. It can be cached in your web browser and also with your domain management tool like Cloudflare's CDN. +::: + diff --git a/docusaurus/docs/cms/admin-panel-customization/host-port-path.md b/docusaurus/docs/cms/admin-panel-customization/host-port-path.md index d9c20aa383..1fb98cb887 100644 --- a/docusaurus/docs/cms/admin-panel-customization/host-port-path.md +++ b/docusaurus/docs/cms/admin-panel-customization/host-port-path.md @@ -16,7 +16,7 @@ By default, Strapi's [admin panel](/cms/admin-panel-customization) is exposed vi ## Update the admin panel's path only -Unless you chose to deploy Strapi's back-end server and admin panel server on different servers (see [deployment](/cms/admin-panel-customization/deployment)), by default: +Unless you chose to deploy Strapi's back-end server and admin panel server on different servers (see [deployment](/cms/configurations/admin-panel#deployment)), by default: - The back-end server and the admin panel server of Strapi both run on the same host and port, which is `http://localhost:1337/`. - The admin panel is accessible at the `/admin` path while the back-end server is accessible at the `/api` path. @@ -58,7 +58,7 @@ export default ({ env }) => ({ ## Update the admin panel's host and port -If the admin panel and the back-end server of Strapi are not hosted on the same server (see [deployment](/cms/admin-panel-customization/deployment)), you will need to update the host and port of the admin panel. +If the admin panel and the back-end server of Strapi are not hosted on the same server (see [deployment](/cms/configurations/admin-panel#deployment)), you will need to update the host and port of the admin panel. This is done in the admin panel configuration file, for example to host the admin panel on `my-host.com:3000` properties should be updated follows: diff --git a/docusaurus/docs/cms/admin-panel-customization/locales-translations.md b/docusaurus/docs/cms/admin-panel-customization/locales-translations.md new file mode 100644 index 0000000000..679df9eaea --- /dev/null +++ b/docusaurus/docs/cms/admin-panel-customization/locales-translations.md @@ -0,0 +1,154 @@ +--- +title: Locales & translations +description: Learn how to update locales and extend translations in the Strapi admin panel. +displayed_sidebar: cmsSidebar +sidebar_label: Locales & translations +toc_max_heading_level: 4 +tags: +- admin panel +- admin panel customization +--- + +# Locales & translations + +The admin panel always ships with English translations, but can display additional languages. You can also override any text that appears in the interface. +The present page shows how to define your own locales and extend Strapi or plugin translations from the project codebase. + +## Defining locales + +To update the list of available locales in the admin panel, use the `config.locales` array: + + + + +```jsx title="/src/admin/app.js" +export default { + config: { + locales: ["ru", "zh"], + }, + bootstrap() {}, +}; +``` + + + + + +```jsx title="/src/admin/app.ts" +export default { + config: { + locales: ["ru", "zh"], + }, + bootstrap() {}, +}; +``` + + + + +:::note Notes + +- The `en` locale cannot be removed from the build as it is both the fallback (i.e. if a translation is not found in a locale, the `en` will be used) and the default locale (i.e. used when a user opens the administration panel for the first time). +- The full list of available locales is accessible on . + +::: + +## Extending translations + +Translation key/value pairs are declared in `@strapi/admin/admin/src/translations/[language-name].json` files. + +These keys can be extended through the `config.translations` key: + + + + +```js title="/src/admin/app.js" +export default { + config: { + locales: ["fr"], + translations: { + fr: { + "Auth.form.email.label": "test", + Users: "Utilisateurs", + City: "CITY (FRENCH)", + // Customize the label of the Content Manager table. + Id: "ID french", + }, + }, + }, + bootstrap() {}, +}; +``` + + + + + +```js title="/src/admin/app.ts" +export default { + config: { + locales: ["fr"], + translations: { + fr: { + "Auth.form.email.label": "test", + Users: "Utilisateurs", + City: "CITY (FRENCH)", + // Customize the label of the Content Manager table. + Id: "ID french", + }, + }, + }, + bootstrap() {}, +}; +``` + + + + +A plugin's key/value pairs are declared independently in the plugin's files at `/admin/src/translations/[language-name].json`. These key/value pairs can similarly be extended in the `config.translations` key by prefixing the key with the plugin's name (i.e. `[plugin name].[key]: 'value'`) as in the following example: + + + + +```js title="/src/admin/app.js" +export default { + config: { + locales: ["fr"], + translations: { + fr: { + "Auth.form.email.label": "test", + // Translate a plugin's key/value pair by adding the plugin's name as a prefix + // In this case, we translate the "plugin.name" key of plugin "content-type-builder" + "content-type-builder.plugin.name": "Constructeur de Type-Contenu", + }, + }, + }, + bootstrap() {}, +}; +``` + + + + + +```js title="/src/admin/app.ts" +export default { + config: { + locales: ["fr"], + translations: { + fr: { + "Auth.form.email.label": "test", + // Translate a plugin's key/value pair by adding the plugin's name as a prefix + // In this case, we translate the "plugin.name" key of plugin "content-type-builder" + "content-type-builder.plugin.name": "Constructeur de Type-Contenu", + }, + }, + }, + bootstrap() {}, +}; +``` + + + + +If more translations files should be added, place them in the `/src/admin/extensions/translations` folder. diff --git a/docusaurus/docs/cms/admin-panel-customization/logos.md b/docusaurus/docs/cms/admin-panel-customization/logos.md new file mode 100644 index 0000000000..920181c51c --- /dev/null +++ b/docusaurus/docs/cms/admin-panel-customization/logos.md @@ -0,0 +1,93 @@ +--- +title: Logos +description: Customize the logos displayed in Strapi's admin panel. +displayed_sidebar: cmsSidebar +sidebar_label: Logos +toc_max_heading_level: 4 +tags: +- admin panel +- admin panel customization +--- + +# Logos + +Strapi's admin panel displays its branding on both the login screen and in the main navigation. Replacing these images allows you to match the interface to your identity. The present page shows how to override the two logo files via the admin panel configuration. If you prefer uploading them directly in the UI, see [Customizing the logo](/cms/features/admin-panel#customizing-the-logo). + +The Strapi admin panel displays a logo in 2 different locations, represented by 2 different keys in the admin panel configuration: + +| Location in the UI | Configuration key to update | +| ---------------------- | --------------------------- | +| On the login page | `config.auth.logo` | +| In the main navigation | `config.menu.logo` | + +:::note +Logos uploaded via the admin panel supersede any logo set through the configuration files. +::: + +### Logos location in the admin panel + + + +The logo handled by `config.auth.logo` logo is only shown on the login screen: + +![Location of the auth logo](/img/assets/development/config-auth-logo.png) + +The logo handled by `config.menu.logo` logo is located in the main navigation at the top left corner of the admin panel: + +![Location of Menu logo](/img/assets/development/config-menu-logo.png) + +### Updating logos + +To update the logos, put image files in the `/src/admin/extensions` folder, import these files in `src/admin/app` and update the corresponding keys as in the following example: + + + + +```jsx title="/src/admin/app.js" +import AuthLogo from "./extensions/my-auth-logo.png"; +import MenuLogo from "./extensions/my-menu-logo.png"; + +export default { + config: { + // … other configuration properties + auth: { // Replace the Strapi logo in auth (login) views + logo: AuthLogo, + }, + menu: { // Replace the Strapi logo in the main navigation + logo: MenuLogo, + }, + // … other configuration properties + + bootstrap() {}, +}; +``` + + + + + +```jsx title="/src/admin/app.ts" +import AuthLogo from "./extensions/my-auth-logo.png"; +import MenuLogo from "./extensions/my-menu-logo.png"; + +export default { + config: { + // … other configuration properties + auth: { // Replace the Strapi logo in auth (login) views + logo: AuthLogo, + }, + menu: { // Replace the Strapi logo in the main navigation + logo: MenuLogo, + }, + // … other configuration properties + + bootstrap() {}, +}; +``` + + + + +:::note +There is no size limit for image files set through the configuration files. +::: diff --git a/docusaurus/docs/cms/admin-panel-customization/options.md b/docusaurus/docs/cms/admin-panel-customization/options.md index 5bcbf6e53f..bbb1de316f 100644 --- a/docusaurus/docs/cms/admin-panel-customization/options.md +++ b/docusaurus/docs/cms/admin-panel-customization/options.md @@ -38,14 +38,14 @@ The `config` object of `/src/admin/app.[tsx|js]` accepts the following parameter | Parameter | Type | Description | | ------------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------- | -| `auth` | Object | Accepts a `logo` key to replace the default Strapi [logo](#logos) on login screen | -| `head` | Object | Accepts a `favicon` key to replace the default Strapi [favicon](#favicon) | -| `locales` | Array of Strings | Defines availables locales (see [updating locales](#locales)) | -| `translations` | Object | [Extends the translations](#extending-translations) | -| `menu` | Object | Accepts the `logo` key to change the [logo](#logos) in the main navigation | -| `theme.light` and `theme.dark` | Object | [Overwrite theme properties](#theme-extension) for Light and Dark modes | -| `tutorials` | Boolean | Toggles [displaying the video tutorials](#tutorial-videos) | -| `notifications` | Object | Accepts the `releases` key (Boolean) to toggle [displaying notifications about new releases](#releases-notifications) | +| `auth` | Object | Accepts a `logo` key to replace the default Strapi [logo](/cms/admin-panel-customization/logos) on login screen | +| `head` | Object | Accepts a `favicon` key to replace the default Strapi [favicon](/cms/admin-panel-customization/favicon) | +| `locales` | Array of Strings | Defines availables locales (see [updating locales](/cms/admin-panel-customization/locales-translations)) | +| `translations` | Object | [Extends the translations](/cms/admin-panel-customization/locales-translations#extending-translations) | +| `menu` | Object | Accepts the `logo` key to change the [logo](/cms/admin-panel-customization/logos) in the main navigation | +| `theme.light` and `theme.dark` | Object | [Overwrite theme properties](/cms/admin-panel-customization/theme-extension) for Light and Dark modes | +| `tutorials` | Boolean | Toggles [displaying the video tutorials](/cms/configurations/admin-panel) | +| `notifications` | Object | Accepts the `releases` key (Boolean) to toggle [displaying notifications about new releases](/cms/configurations/admin-panel) |
Example of a custom configuration for the admin panel: @@ -189,268 +189,5 @@ Light and dark colors are also found [on GitHub](https://github.com/strapi/desig -
- -## Locales - -To update the list of available locales in the admin panel, use the `config.locales` array: - - - - -```jsx title="./my-app/src/admin/app.js" -export default { - config: { - locales: ["ru", "zh"], - }, - bootstrap() {}, -}; -``` - - - - - -```jsx title="./my-app/src/admin/app.ts" -export default { - config: { - locales: ["ru", "zh"], - }, - bootstrap() {}, -}; -``` - - - - -:::note NOTES - -- The `en` locale cannot be removed from the build as it is both the fallback (i.e. if a translation is not found in a locale, the `en` will be used) and the default locale (i.e. used when a user opens the administration panel for the first time). -- The full list of available locales is accessible on . - -::: - -### Extending translations - -Translation key/value pairs are declared in `@strapi/admin/admin/src/translations/[language-name].json` files. These keys can be extended through the `config.translations` key: - - - - -```js title="./my-app/src/admin/app.js" -export default { - config: { - locales: ["fr"], - translations: { - fr: { - "Auth.form.email.label": "test", - Users: "Utilisateurs", - City: "CITY (FRENCH)", - // Customize the label of the Content Manager table. - Id: "ID french", - }, - }, - }, - bootstrap() {}, -}; -``` - - - - - -```js title="./my-app/src/admin/app.ts" -export default { - config: { - locales: ["fr"], - translations: { - fr: { - "Auth.form.email.label": "test", - Users: "Utilisateurs", - City: "CITY (FRENCH)", - // Customize the label of the Content Manager table. - Id: "ID french", - }, - }, - }, - bootstrap() {}, -}; -``` - - - - -A plugin's key/value pairs are declared independently in the plugin's files at `./admin/src/translations/[language-name].json`. These key/value pairs can similarly be extended in the `config.translations` key by prefixing the key with the plugin's name (i.e. `[plugin name].[key]: 'value'`) as in the following example: - - - - -```js title="./my-app/src/admin/app.js" -export default { - config: { - locales: ["fr"], - translations: { - fr: { - "Auth.form.email.label": "test", - // Translate a plugin's key/value pair by adding the plugin's name as a prefix - // In this case, we translate the "plugin.name" key of plugin "content-type-builder" - "content-type-builder.plugin.name": "Constructeur de Type-Contenu", - }, - }, - }, - bootstrap() {}, -}; -``` - - - - - -```js title="./my-app/src/admin/app.ts" -export default { - config: { - locales: ["fr"], - translations: { - fr: { - "Auth.form.email.label": "test", - // Translate a plugin's key/value pair by adding the plugin's name as a prefix - // In this case, we translate the "plugin.name" key of plugin "content-type-builder" - "content-type-builder.plugin.name": "Constructeur de Type-Contenu", - }, - }, - }, - bootstrap() {}, -}; -``` - - - - -If more translations files should be added, place them in `./src/admin/extensions/translations` folder. - -## Logos - -The Strapi admin panel displays a logo in 2 different locations, represented by 2 different keys in the admin panel configuration: - -| Location in the UI | Configuration key to update | -| ---------------------- | --------------------------- | -| On the login page | `config.auth.logo` | -| In the main navigation | `config.menu.logo` | - -:::note -Both logos can also be customized directly via the admin panel (see [Customizing the logo](/cms/features/admin-panel)). -Logos uploaded via the admin panel supersede any logo set through the configuration files. -::: - -### Logos location in the admin panel - - - -The logo handled by `config.auth.logo` logo is only shown on the login screen: - -![Location of the auth logo](/img/assets/development/config-auth-logo.png) - -The logo handled by `config.menu.logo` logo is located in the main navigation at the top left corner of the admin panel: - -![Location of Menu logo](/img/assets/development/config-menu-logo.png) - -### Updating logos - -To update the logos, put image files in the `/src/admin/extensions` folder, import these files in `src/admin/app.[tsx|js]` and update the corresponding keys as in the following example: - - - - -```jsx title="/src/admin/app.js" -import AuthLogo from "./extensions/my-auth-logo.png"; -import MenuLogo from "./extensions/my-menu-logo.png"; - -export default { - config: { - // … other configuration properties - auth: { // Replace the Strapi logo in auth (login) views - logo: AuthLogo, - }, - menu: { // Replace the Strapi logo in the main navigation - logo: MenuLogo, - }, - // … other configuration properties - - bootstrap() {}, -}; -``` - - - - - -```jsx title="/src/admin/app.ts" -import AuthLogo from "./extensions/my-auth-logo.png"; -import MenuLogo from "./extensions/my-menu-logo.png"; - -export default { - config: { - // … other configuration properties - auth: { // Replace the Strapi logo in auth (login) views - logo: AuthLogo, - }, - menu: { // Replace the Strapi logo in the main navigation - logo: MenuLogo, - }, - // … other configuration properties - - bootstrap() {}, -}; -``` - - - -:::note -There is no size limit for image files set through the configuration files. -::: - -## Favicon - -To replace the favicon: - -1. Create a `/src/admin/extensions/` folder if the folder does not already exist. -2. Upload your favicon into `/src/admin/extensions/`. -3. Replace the existing **favicon.png|ico** file at the Strapi application root with a custom `favicon.png|ico` file. -4. Update `/src/admin/app.[tsx|js]` with the following: - - ```js title="./src/admin/app.js" - import favicon from "./extensions/favicon.png"; - - export default { - config: { - // replace favicon with a custom icon - head: { - favicon: favicon, - }, - }, - }; - ``` - -5. Rebuild, launch and revisit your Strapi app by running `yarn build && yarn develop` in the terminal. - -:::tip -This same process may be used to replace the login logo (i.e. `AuthLogo`) and menu logo (i.e. `MenuLogo`) (see [logos customization documentation](#logos)). -::: - -:::caution -Make sure that the cached favicon is cleared. It can be cached in your web browser and also with your domain management tool like Cloudflare's CDN. -::: - -## Theme extension - -Strapi applications can be displayed either in Light or Dark mode (see [administrator profile setup in the User Guide](/cms/getting-started/setting-up-admin-panel#setting-up-your-administrator-profile)), and both can be extended through custom theme settings. - -To extend the theme, use either: - -- the `config.theme.light` key for the Light mode -- the `config.theme.dark` key for the Dark mode - -:::strapi Strapi Design System -The default defines various theme-related keys (shadows, colors…) that can be updated through the `config.theme.light` and `config.theme.dark` keys in `./admin/src/app.js`. The is fully customizable and has a dedicated documentation. -::: + diff --git a/docusaurus/docs/cms/admin-panel-customization/theme-extension.md b/docusaurus/docs/cms/admin-panel-customization/theme-extension.md new file mode 100644 index 0000000000..1288508c89 --- /dev/null +++ b/docusaurus/docs/cms/admin-panel-customization/theme-extension.md @@ -0,0 +1,23 @@ +--- +title: Theme extension +description: Extend Strapi's admin panel theme. +displayed_sidebar: cmsSidebar +sidebar_label: Theme extension +toc_max_heading_level: 4 +tags: +- admin panel +- admin panel customization +--- + +# Theme extension + +The Strapi [admin panel](/cms/admin-panel-customization) can be displayed either in light or dark mode (see [profile setup](/cms/getting-started/setting-up-admin-panel#setting-up-your-administrator-profile)), and both can be extended through custom theme settings. + +To extend the theme, use either: + +- the `config.theme.light` key for the Light mode +- the `config.theme.dark` key for the Dark mode + +:::strapi Strapi Design System +The default defines various theme-related keys (shadows, colors…) that can be updated through the `config.theme.light` and `config.theme.dark` keys in `./admin/src/app.js`. The is fully customizable and has a dedicated documentation. +::: diff --git a/docusaurus/docs/cms/backend-customization.md b/docusaurus/docs/cms/backend-customization.md index 48508def24..7312e88103 100644 --- a/docusaurus/docs/cms/backend-customization.md +++ b/docusaurus/docs/cms/backend-customization.md @@ -28,7 +28,7 @@ But the Strapi software itself includes 2 different parts: Throughout this developer documentation, 'back end' refers _exclusively_ to the back-end part of Strapi. -The [User Guide](/cms/intro) explains how to use the admin panel and the [admin panel customization section](/cms/admin-panel-customization) details the various customization options available for the admin panel. +The [Getting Started > Admin panel page](/cms/features/admin-panel) gives an admin panel overview and the [admin panel customization section](/cms/admin-panel-customization) details the various customization options available for the admin panel. ::: The Strapi back end runs an HTTP server based on , a back-end JavaScript framework. diff --git a/docusaurus/docs/cms/configurations/admin-panel.md b/docusaurus/docs/cms/configurations/admin-panel.md index 4ad9688007..f8095a360b 100644 --- a/docusaurus/docs/cms/configurations/admin-panel.md +++ b/docusaurus/docs/cms/configurations/admin-panel.md @@ -214,7 +214,7 @@ The authentication system, including [SSO configuration](/cms/configurations/gui By default, Strapi's admin panel is exposed via `http://localhost:1337/admin`. For security reasons, the host, port, and path can be updated. -Unless you chose to deploy Strapi's back-end server and admin panel server on different servers (see [deployment](/cms/admin-panel-customization/deployment)), by default: +Unless you chose to deploy Strapi's back-end server and admin panel server on different servers (see [deployment](/cms/configurations/admin-panel#deployment)), by default: - The back-end server and the admin panel server both run on the same host and port (`http://localhost:1337/`) - The admin panel is accessible at the `/admin` path while the back-end server is accessible at the `/api` path @@ -270,15 +270,61 @@ export default ({ env }) => ({ -### Deploy on different servers +## Deployment -To deploy the admin panel and the back-end on completely different servers, you need to configure both the server (`/config/server`) and admin panel (`/config/admin-panel`) configurations. +The front-end part of Strapi is called the admin panel. The admin panel presents a graphical user interface to help you structure and manage the content that will be accessible to your application's own front-end through Strapi's Content API. -The following example setup allows you to serve the admin panel from one domain while the API runs on another: +The admin panel is a React-based single-page application that encapsulates all the features and installed plugins of a Strapi application. + +The [back-end server](/cms/backend-customization) of Strapi serves the Content API which provides endpoints to your content. + +By default, the back-end server and the admin panel server are deployed on the same server. But the admin panel and the back-end server are independent and can be deployed on different servers, which brings us to different scenarios: + +- Deploy the entire project on the same server. +- Deploy the administration panel on a server (AWS S3, Azure, etc) different from the API server. + +Build configurations differ for each case. + +Before deployment, the admin panel needs to be built, by running the following command from the project's root directory: + + + + + +```sh +yarn build +``` + + + + + +```sh +npm run build +``` + + + + + +This will replace the folder's content located at `./build`. Visit to make sure customizations have been taken into account. + +### Same server + +Deploying the admin panel and the back end (API) of Strapi on the same server is the default behavior. The build configuration will be automatically set. The server will start on the defined port and the administration panel will be accessible through `http://yourdomain.com:1337/admin`. + +:::tip +You might want to [change the path to access the administration panel](#server-configuration). +::: + +### Different servers + +To deploy the admin panel and the back end (API) of Strapi on different servers, use the following configuration: + ```js title="/config/server.js" module.exports = ({ env }) => ({ host: env("HOST", "0.0.0.0"), @@ -299,6 +345,7 @@ module.exports = ({ env }) => ({ ``` + ```js title="/config/server.ts" @@ -328,6 +375,10 @@ With this configuration: - All API requests from the panel will be sent to `http://yourbackend.com` - The backend server will not serve any static admin files due to `serveAdminPanel: false` +:::note +If you add a path to the `url` option, it won't prefix your application. To do so, use a proxy server like Nginx (see [optional software deployment guides](/cms/deployment#additional-resources)). +::: + ## Feature flags The feature flags can be configured with the following parameters: diff --git a/docusaurus/docs/cms/configurations/guides/configure-sso.md b/docusaurus/docs/cms/configurations/guides/configure-sso.md index 2d81c17721..dc8346153e 100644 --- a/docusaurus/docs/cms/configurations/guides/configure-sso.md +++ b/docusaurus/docs/cms/configurations/guides/configure-sso.md @@ -327,7 +327,7 @@ const strategyInstance = new Strategy(configuration, ({ email, username }, done) ### Authentication events -The SSO feature adds a new [authentication event](/cms/configurations/admin-panel#available-options): `onSSOAutoRegistration`. +The SSO feature adds a new [authentication event](/cms/configurations/admin-panel#authentication): `onSSOAutoRegistration`. This event is triggered whenever a user is created using the auto-register feature added by SSO. It contains the created user (`event.user`), and the provider used to make the registration (`event.provider`). diff --git a/docusaurus/docs/cms/deployment.md b/docusaurus/docs/cms/deployment.md index bd2468d749..8bf28aa6ef 100644 --- a/docusaurus/docs/cms/deployment.md +++ b/docusaurus/docs/cms/deployment.md @@ -187,7 +187,7 @@ For more information, consult the [TypeScript documentation](/cms/typescript/dev ### Advanced configurations -If you want to host the administration on another server than the API, [please take a look at this dedicated section](/cms/admin-panel-customization/deployment). +If you want to host the administration on another server than the API, [please take a look at this dedicated section](/cms/configurations/admin-panel#deployment). ## Additional resources diff --git a/docusaurus/docs/cms/features/admin-panel.md b/docusaurus/docs/cms/features/admin-panel.md index 490f9cce36..313bff9010 100644 --- a/docusaurus/docs/cms/features/admin-panel.md +++ b/docusaurus/docs/cms/features/admin-panel.md @@ -123,7 +123,7 @@ The default Strapi logos, displayed in the main navigation of a Strapi applicati Once uploaded, the new logo can be replaced with another one , or reset with the default Strapi logo or the logo set in the configuration files. :::note -Both logos can also be customized programmatically via the Strapi application's configuration files (see [Admin panel customization](/cms/admin-panel-customization/options#logos)). However, the logos uploaded via the admin panel supersedes any logo set through the configuration files. +Both logos can also be customized programmatically via the Strapi application's configuration files (see [Admin panel customization](/cms/admin-panel-customization/logos)). However, the logos uploaded via the admin panel supersedes any logo set through the configuration files. :::