snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

docs/develop/integrate/plugins/components/webapp/hello-world.md

@@ -0,0 +1,178 @@
+---
+title: "Web app quick start"
+sidebar_position: -10
+---
+
+This tutorial will walk you through the basics of extending the Mattermost web app.
+
+Note that the steps below are intentionally very manual to explain all of the pieces fitting together. In practice, we recommend referencing [mattermost-plugin-starter-template](https://github.com/mattermost/mattermost-plugin-starter-template) for helpful build scripts. Also, the plugin API changed in Mattermost 5.2. Consult the [migration](/developers/integrate/plugins/migration) document to upgrade older plugins.
+
+## Prerequisites
+
+Plugins, just like the Mattermost web app itself, are built using [ReactJS](https://react.dev/) with [Redux](https://redux.js.org/). Make sure to install [npm](https://www.npmjs.com/get-npm) to manage your JavaScript dependencies.
+
+You'll also need a Mattermost server to install and test the plugin. This server must have [Enable](https://docs.mattermost.com/administration/config-settings.html#enable-plugins) set to true in the [PluginSettings](https://docs.mattermost.com/administration/config-settings.html#plugins-beta) section of its config file. If you want to upload plugins via the System Console or API, you'll also need to set [EnableUploads](https://docs.mattermost.com/administration/config-settings.html#enable-plugin-uploads) to true in the same section.
+
+## Set up the workspace
+
+Create a directory to act as your plugin workspace. With that directory, create and switch to a `webapp` directory:
+
+```bash
+mkdir webapp
+cd webapp
+```
+
+Install the necessary NPM dependencies:
+
+```bash
+npm install --save-dev @babel/core @babel/preset-env @babel/preset-react babel-loader webpack webpack-cli
+npm install --save react
+```
+
+Configure Webpack by creating a `webpack.config.js` file:
+
+```js
+var path = require('path');
+
+module.exports = {
+    entry: [
+        './src/index.jsx',
+    ],
+    resolve: {
+        modules: [
+            'src',
+            'node_modules',
+        ],
+        extensions: ['*', '.js', '.jsx'],
+    },
+    module: {
+        rules: [
+            {
+                test: /\.(js|jsx)$/,
+                exclude: /node_modules/,
+                use: {
+                    loader: 'babel-loader',
+                    options: {
+                        presets: ['@babel/preset-react',
+                            [
+                                "@babel/preset-env",
+                                {
+                                    "modules": "commonjs",
+                                    "targets": {
+                                        "node": "current"
+                                    }
+                                }
+                            ]
+                        ],
+                    },
+                },
+            },
+        ],
+    },
+    externals: {
+        react: 'React',
+    },
+    output: {
+        path: path.join(__dirname, '/dist'),
+        publicPath: '/',
+        filename: 'main.js',
+    },
+};
+```
+
+Observe that `react` is specified as an external library. This allows you to test your code locally (e.g. with [jest](https://jestjs.io/) and snapshots) but leverage the version of React shipped with Mattermost to avoid bloating your plugin.
+
+Now create the entry point file and output directory:
+```bash
+mkdir src dist
+touch src/index.jsx
+```
+
+Then populate `src/index.jsx` with the following:
+```jsx
+import React from 'react';
+
+// Courtesy of https://feathericons.com/
+const Icon = () => <i className='icon fa fa-plug'/>;
+
+class HelloWorldPlugin {
+    initialize(registry, store) {
+        registry.registerChannelHeaderButtonAction(
+            // icon - JSX element to use as the button's icon
+            <Icon />,
+            // action - a function called when the button is clicked, passed the channel and channel member as arguments
+            // null,
+            () => {
+                alert("Hello World!");
+            },
+            // dropdown_text - string or JSX element shown for the dropdown button description
+            "Hello World",
+        );
+    }
+}
+
+window.registerPlugin('com.mattermost.webapp-hello-world', new HelloWorldPlugin());
+```
+
+Generate a minified bundle ready to install as a web app plugin:
+
+```bash
+./node_modules/.bin/webpack --mode=production
+```
+
+Now, we'll need to define the required manifest describing your plugin's entry point. Create a file named `plugin.json` with the following contents:
+
+```json
+{
+    "id": "com.mattermost.webapp-hello-world",
+    "name": "Hello World",
+    "webapp": {
+        "bundle_path": "main.js"
+    }
+}
+```
+
+This manifest gives the server the location of your components within your plugin bundle. Consult the [manifest reference](/developers/integrate/plugins/manifest-reference) for more details, including how to define a minimum required server version for your plugin.
+
+Note that you may also use `plugin.yaml` to define the manifest.
+
+Bundle the manifest and entry point into a tar file:
+
+```bash
+mkdir -p com.mattermost.webapp-hello-world
+cp -r dist/main.js com.mattermost.webapp-hello-world/
+cp plugin.json com.mattermost.webapp-hello-world/
+tar -czvf plugin.tar.gz com.mattermost.webapp-hello-world
+```
+
+You should now have a file named `plugin.tar.gz` in your workspace. Congratulations! This is your first web app plugin!
+
+## Install the plugin
+
+Install the plugin in one of the following ways:
+
+1) Through System Console UI:
+
+```text
+- Log in to Mattermost as a System Admin.
+- Open the System Console at `/admin_console`
+- Navigate to **Plugins > Plugin Management** and upload the `plugin.tar.gz` you generated above.
+- Click **Enable** under the plugin after it has uploaded.
+```
+
+2) Or, manually:
+
+    - Extract `plugin.tar.gz` to a folder with the same name as the plugin id you specified in ``plugin.json``, in this case `com.mattermost.server-hello-world/`.
+    - Add the plugin to the directory set by **PluginSettings > Directory** in your ``config.json`` file. If none is set, defaults to `./plugins` relative to your Mattermost installation directory. The resulting directory structure should look something like:
+
+      ```
+      mattermost/
+          plugins/
+              com.mattermost.webapp-hello-world/
+                  plugin.json
+                  main.js
+      ```
+    - Restart the Mattermost server.
+    - Enable the plugin in **System Console > Plugins > Plugin Management**.
+
+Navigate to a regular Mattermost page and observe the new icon in the channel header. Click the icon and observe the alert dialog.