Skip to content

Commit

Permalink
Merge pull request #1963 from strapi/feat/add-vite
Browse files Browse the repository at this point in the history 
Add vite bundler documentation to admin panel customisation
  • Loading branch information
@meganelacheny
meganelacheny authored Jan 24, 2024
2 parents 93e14ab + 50e803d commit 9979c26
Show file tree
Hide file tree
Showing 2 changed files with 115 additions and 29 deletions.
95 changes: 86 additions & 9 deletions docusaurus/docs/dev-docs/admin-panel-customization.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,13 @@ import FeedbackCallout from '/docs/snippets/backend-customization-feedback-cta.m
const captionStyle = {fontSize: '12px'}
const imgStyle = {width: '100%', margin: '0' }

The admin panel is a `node_module` that is similar to a plugin, except that it encapsulates all the installed plugins of a Strapi application. Some of its aspects can be [customized](#customization-options), and plugins can also [extend](#extension) it.
The admin panel is a React-based single-page application. It encapsulates all the installed plugins of a Strapi application. Some of its aspects can be [customized](#customization-options), and plugins can also [extend](#extension) it.

To start your strapi instance with hot reloading while developing, run the following command:

```bash
cd my-app # cd into the root directory of the Strapi application project
strapi develop
strapi develop --watch-admin
```

## Customization options
Expand All @@ -27,7 +27,6 @@ Customizing the admin panel is helpful to better reflect your brand identity or
- The [configuration object](#configuration-options) allows replacing the logos and favicon, defining locales and extending translations, extending the theme, and disabling some Strapi default behaviors like displaying video tutorials or notifications about new Strapi releases.
- The [WYSIWYG editor](#wysiwyg-editor) can be replaced or customized.
- The [email templates](#email-templates) should be customized using the Users and Permissions plugin.
- The [webpack configuration](#webpack-configuration) based on webpack 5 can also be extended for advanced customization

### Access URL

Expand Down Expand Up @@ -537,15 +536,24 @@ export default {

Email templates should be edited through the admin panel, using the [Users and Permissions plugin settings](/user-docs/settings/configuring-users-permissions-plugin-settings#configuring-email-templates).

### Webpack configuration
## Bundlers (experimental)

2 different bundlers can be used with your Strapi application, [webpack](#webpack) and [vite](#vite).

### Webpack

In v4 this is the defacto bundler that Strapi uses to build the admin panel.

:::prerequisites
Make sure to rename the default `webpack.config.example.js` file into `webpack.config.js` before customizing webpack.
Make sure to rename the default `webpack.config.example.js` file into `webpack.config.[js|ts]` before customizing webpack.
:::

In order to extend the usage of webpack v5, define a function that extends its configuration inside `./my-app/src/admin/webpack.config.js`:
In order to extend the usage of webpack v5, define a function that extends its configuration inside `./my-app/src/admin/webpack.config.[js|ts]`:

```js
<Tabs groupId="js-ts">
<TabItem value="js" label="JavaScript">

```js title="./my-app/src/admin/webpack.config.js"
module.exports = (config, webpack) => {
// Note: we provide webpack above so you should not `require` it

Expand All @@ -557,10 +565,79 @@ module.exports = (config, webpack) => {
};
```

:::note
Only `./src/admin/app.js` and the files under the `./src/admin/extensions` folder are being watched by the webpack dev server.
</TabItem>

<TabItem value="ts" label="TypeScript">

```ts title="./my-app/src/admin/webpack.config.ts"
export default (config, webpack) => {
// Note: we provide webpack above so you should not `require` it

// Perform customizations to webpack config
config.plugins.push(new webpack.IgnorePlugin(/\/__tests__\//));

// Important: return the modified config
return config;
};
```

</TabItem>
</Tabs>

### Vite

:::caution
This is considered experimental. Please report any issues you encounter.
:::

To use `vite` as a bundler you will need to pass it as an option to the `strapi develop` command:

```bash
strapi develop --watch-admin --bundler=vite
```

To extend the usage of `vite`, define a function that extends its configuration inside `./my-app/src/admin/vite.config.[js|ts]`:

<Tabs groupId="js-ts">
<TabItem value="js" label="JavaScript">

```js title="./my-app/src/admin/vite.config.js"
const { mergeConfig } = require("vite");

module.exports = (config) => {
// Important: always return the modified config
return mergeConfig(config, {
resolve: {
alias: {
"@": "/src",
},
},
});
};
```

</TabItem>

<TabItem value="ts" label="TypeScript">

```ts title="./my-app/src/admin/vite,config.ts"
import { mergeConfig } from "vite";

export default (config) => {
// Important: always return the modified config
return mergeConfig(config, {
resolve: {
alias: {
"@": "/src",
},
},
});
};
```

</TabItem>
</Tabs>

## Extension

There are 2 use cases to extend the admin panel:
Expand Down
49 changes: 29 additions & 20 deletions docusaurus/docs/dev-docs/cli.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,26 +59,30 @@ Strapi modifies/creates files at runtime and needs to restart when new files are

Strapi also adds middlewares to support HMR (Hot Module Replacement) for the administration panel. This allows you to customize the administration panel without having to restart the application or run a separate server. This is only added when you use the `--watch-admin` command.

```
```bash
strapi develop
options: [--no-build |--watch-admin |--browser |--debug |--silent]
```

- **strapi develop**<br/>
Starts your application with the autoReload enabled
- **strapi develop --open**<br/>
Starts your application with the autoReload enabled & open your default browser with the administration panel running.
- **strapi develop --watch-admin**<br/>
Starts your application with the autoReload enabled and the front-end development server. It allows you to customize the administration panel.
- [DEPRECATED] **strapi develop --no-build**<br/>
Starts your application with the autoReload enabled and skip the administration panel build process
- [DEPRECATED] **strapi develop --watch-admin --browser 'google chrome'**<br/>
Starts your application with the autoReload enabled and the front-end development server. It allows you to customize the administration panel. Provide a browser name to use instead of the default one, `false` means stop opening the browser.
| Option | Type | Description | Default |
| ------------------ | :----: | ---------------------------------------------------------------------------------------------------------------- | --------- |
| `--bundler` | string | Specifies the bundler to use, either `webpack` or `vite`x | `webpack` |
| `-d, --debug` | - | Enable debugging mode with verbose logs | false |
| `--ignore-prompts` | - | Ignore all prompts | false |
| `--open` | - | Open the admin in your browser (default: true) | false |
| `--polling` | - | Watch for file changes in network directories | false |
| `--silent` | - | Don't log anything | false |
| `--watch-admin` | - | Watch the admin panel for hot changes | false |
| `--no-build` | - | [DEPRECATED] Starts your application with the autoReload enabled and skip the administration panel build process | - |
| `--browser` | string | [DEPRECATED] Provide a browser name to use instead of the default one | - |

:::warning
You should never use this command to run a Strapi application in production.
:::

:::caution
Using the `vite` option as a bundler is considered experimental.
:::

## strapi start

Start a Strapi application with autoReload disabled.
Expand All @@ -94,14 +98,19 @@ Builds your admin panel.
strapi build
```

| Option | Type | Description |
| ------------------- | :--: | -------------------------------------------------------- |
| `-d, --debug` | - | Enable debugging mode with verbose logs (default: false) |
| `--minify` | - | Minify the output (default: true) |
| `--no-optimization` | - | [DEPRECATED]: use minify instead |
| `--silent` | - | Don't log anything (default: false) |
| `--sourcemaps` | - | Produce sourcemaps (default: false) |
| `--stats` | - | Print build statistics to the console (default: false) |
| Option | Type | Description | Default |
| ------------------- | :----: | ------------------------------------------------------------------- | --------- |
| `--bundler` | string | Specifies the bundler you'd like to use, either `webpack` or `vite` | `webpack` |
| `-d, --debug` | - | Enable debugging mode with verbose logs | false |
| `--minify` | - | Minify the output | true |
| `--no-optimization` | - | [DEPRECATED]: use minify instead | - |
| `--silent` | - | Don't log anything | false |
| `--sourcemaps` | - | Produce sourcemaps | false |
| `--stats` | - | Print build statistics to the console | false |

:::caution
Using the `vite` option as a bundler is considered experimental.
:::

## strapi watch-admin

Expand Down

0 comments on commit 9979c26

Please sign in to comment.