{"id":13400440,"url":"https://github.com/mattermost/mattermost-plugin-starter-template","last_synced_at":"2025-03-14T06:31:40.131Z","repository":{"id":34310733,"uuid":"141299506","full_name":"mattermost/mattermost-plugin-starter-template","owner":"mattermost","description":"Build scripts and templates for writing Mattermost plugins.","archived":false,"fork":false,"pushed_at":"2024-07-24T16:14:51.000Z","size":2065,"stargazers_count":122,"open_issues_count":23,"forks_count":115,"subscribers_count":41,"default_branch":"master","last_synced_at":"2024-07-31T19:24:49.884Z","etag":null,"topics":["hacktoberfest","mattermost","mattermost-plugin","template"],"latest_commit_sha":null,"homepage":"https://developers.mattermost.com/extend/plugins/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mattermost.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-17T14:15:13.000Z","updated_at":"2024-07-24T08:22:29.000Z","dependencies_parsed_at":"2023-11-07T04:44:02.848Z","dependency_job_id":"9a422cb2-d91f-48bd-8d91-e06985359635","html_url":"https://github.com/mattermost/mattermost-plugin-starter-template","commit_stats":null,"previous_names":["mattermost/mattermost-plugin-sample"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattermost%2Fmattermost-plugin-starter-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattermost%2Fmattermost-plugin-starter-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattermost%2Fmattermost-plugin-starter-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattermost%2Fmattermost-plugin-starter-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattermost","download_url":"https://codeload.github.com/mattermost/mattermost-plugin-starter-template/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221440184,"owners_count":16821599,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","mattermost","mattermost-plugin","template"],"created_at":"2024-07-30T19:00:52.053Z","updated_at":"2025-03-14T06:31:40.118Z","avatar_url":"https://github.com/mattermost.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Plugin Starter Template\n\n[![Build Status](https://github.com/mattermost/mattermost-plugin-starter-template/actions/workflows/ci.yml/badge.svg)](https://github.com/mattermost/mattermost-plugin-starter-template/actions/workflows/ci.yml)\n[![E2E Status](https://github.com/mattermost/mattermost-plugin-starter-template/actions/workflows/e2e.yml/badge.svg)](https://github.com/mattermost/mattermost-plugin-starter-template/actions/workflows/e2e.yml)\n\nThis plugin serves as a starting point for writing a Mattermost plugin. Feel free to base your own plugin off this repository.\n\nTo learn more about plugins, see [our plugin documentation](https://developers.mattermost.com/extend/plugins/).\n\nThis template requires node v16 and npm v8. You can download and install nvm to manage your node versions by following the instructions [here](https://github.com/nvm-sh/nvm). Once you've setup the project simply run `nvm i` within the root folder to use the suggested version of node.\n\n## Getting Started\nUse GitHub's template feature to make a copy of this repository by clicking the \"Use this template\" button.\n\nAlternatively shallow clone the repository matching your plugin name:\n```\ngit clone --depth 1 https://github.com/mattermost/mattermost-plugin-starter-template com.example.my-plugin\n```\n\nNote that this project uses [Go modules](https://github.com/golang/go/wiki/Modules). Be sure to locate the project outside of `$GOPATH`.\n\nEdit the following files:\n1. `plugin.json` with your `id`, `name`, and `description`:\n```json\n{\n    \"id\": \"com.example.my-plugin\",\n    \"name\": \"My Plugin\",\n    \"description\": \"A plugin to enhance Mattermost.\"\n}\n```\n\n2. `go.mod` with your Go module path, following the `\u003chosting-site\u003e/\u003crepository\u003e/\u003cmodule\u003e` convention:\n```\nmodule github.com/example/my-plugin\n```\n\n3. `.golangci.yml` with your Go module path:\n```yml\nlinters-settings:\n  # [...]\n  goimports:\n    local-prefixes: github.com/example/my-plugin\n```\n\nBuild your plugin:\n```\nmake\n```\n\nThis will produce a single plugin file (with support for multiple architectures) for upload to your Mattermost server:\n\n```\ndist/com.example.my-plugin.tar.gz\n```\n\n## Development\n\nTo avoid having to manually install your plugin, build and deploy your plugin using one of the following options. In order for the below options to work, you must first enable plugin uploads via your config.json or API and restart Mattermost.\n\n```json\n    \"PluginSettings\" : {\n        ...\n        \"EnableUploads\" : true\n    }\n```\n\n### Development guidance \n\n1. Fewer packages is better: default to the main package unless there's good reason for a new package.\n\n2. Coupling implies same package: don't jump through hoops to break apart code that's naturally coupled.\n\n3. New package for a new interface: a classic example is the sqlstore with layers for monitoring performance, caching and mocking.\n\n4. New package for upstream integration: a discrete client package for interfacing with a 3rd party is often a great place to break out into a new package\n\n### Modifying the server boilerplate\n\nThe server code comes with some boilerplate for creating an api, using slash commands, accessing the kvstore and using the cluster package for jobs. \n\n#### Api\n\napi.go implements the ServeHTTP hook which allows the plugin to implement the http.Handler interface. Requests destined for the `/plugins/{id}` path will be routed to the plugin. This file also contains a sample `HelloWorld` endpoint that is tested in plugin_test.go.\n\n#### Command package\n\nThis package contains the boilerplate for adding a slash command and an instance of it is created in the `OnActivate` hook in plugin.go. If you don't need it you can delete the package and remove any reference to `commandClient` in plugin.go. The package also contains an example of how to create a mock for testing.\n\n#### KVStore package\n\nThis is a central place for you to access the KVStore methods that are available in the `pluginapi.Client`. The package contains an interface for you to define your methods that will wrap the KVStore methods. An instance of the KVStore is created in the `OnActivate` hook.\n\n### Deploying with Local Mode\n\nIf your Mattermost server is running locally, you can enable [local mode](https://docs.mattermost.com/administration/mmctl-cli-tool.html#local-mode) to streamline deploying your plugin. Edit your server configuration as follows:\n\n```json\n{\n    \"ServiceSettings\": {\n        ...\n        \"EnableLocalMode\": true,\n        \"LocalModeSocketLocation\": \"/var/tmp/mattermost_local.socket\"\n    },\n}\n```\n\nand then deploy your plugin:\n```\nmake deploy\n```\n\nYou may also customize the Unix socket path:\n```bash\nexport MM_LOCALSOCKETPATH=/var/tmp/alternate_local.socket\nmake deploy\n```\n\nIf developing a plugin with a webapp, watch for changes and deploy those automatically:\n```bash\nexport MM_SERVICESETTINGS_SITEURL=http://localhost:8065\nexport MM_ADMIN_TOKEN=j44acwd8obn78cdcx7koid4jkr\nmake watch\n```\n\n### Deploying with credentials\n\nAlternatively, you can authenticate with the server's API with credentials:\n```bash\nexport MM_SERVICESETTINGS_SITEURL=http://localhost:8065\nexport MM_ADMIN_USERNAME=admin\nexport MM_ADMIN_PASSWORD=password\nmake deploy\n```\n\nor with a [personal access token](https://docs.mattermost.com/developer/personal-access-tokens.html):\n```bash\nexport MM_SERVICESETTINGS_SITEURL=http://localhost:8065\nexport MM_ADMIN_TOKEN=j44acwd8obn78cdcx7koid4jkr\nmake deploy\n```\n\n### Releasing new versions\n\nThe version of a plugin is determined at compile time, automatically populating a `version` field in the [plugin manifest](plugin.json):\n* If the current commit matches a tag, the version will match after stripping any leading `v`, e.g. `1.3.1`.\n* Otherwise, the version will combine the nearest tag with `git rev-parse --short HEAD`, e.g. `1.3.1+d06e53e1`.\n* If there is no version tag, an empty version will be combined with the short hash, e.g. `0.0.0+76081421`.\n\nTo disable this behaviour, manually populate and maintain the `version` field.\n\n## How to Release\n\nTo trigger a release, follow these steps:\n\n1. **For Patch Release:** Run the following command:\n    ```\n    make patch\n    ```\n   This will release a patch change.\n\n2. **For Minor Release:** Run the following command:\n    ```\n    make minor\n    ```\n   This will release a minor change.\n\n3. **For Major Release:** Run the following command:\n    ```\n    make major\n    ```\n   This will release a major change.\n\n4. **For Patch Release Candidate (RC):** Run the following command:\n    ```\n    make patch-rc\n    ```\n   This will release a patch release candidate.\n\n5. **For Minor Release Candidate (RC):** Run the following command:\n    ```\n    make minor-rc\n    ```\n   This will release a minor release candidate.\n\n6. **For Major Release Candidate (RC):** Run the following command:\n    ```\n    make major-rc\n    ```\n   This will release a major release candidate.\n\n## Q\u0026A\n\n### How do I make a server-only or web app-only plugin?\n\nSimply delete the `server` or `webapp` folders and remove the corresponding sections from `plugin.json`. The build scripts will skip the missing portions automatically.\n\n### How do I include assets in the plugin bundle?\n\nPlace them into the `assets` directory. To use an asset at runtime, build the path to your asset and open as a regular file:\n\n```go\nbundlePath, err := p.API.GetBundlePath()\nif err != nil {\n    return errors.Wrap(err, \"failed to get bundle path\")\n}\n\nprofileImage, err := ioutil.ReadFile(filepath.Join(bundlePath, \"assets\", \"profile_image.png\"))\nif err != nil {\n    return errors.Wrap(err, \"failed to read profile image\")\n}\n\nif appErr := p.API.SetProfileImage(userID, profileImage); appErr != nil {\n    return errors.Wrap(err, \"failed to set profile image\")\n}\n```\n\n### How do I build the plugin with unminified JavaScript?\nSetting the `MM_DEBUG` environment variable will invoke the debug builds. The simplist way to do this is to simply include this variable in your calls to `make` (e.g. `make dist MM_DEBUG=1`).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattermost%2Fmattermost-plugin-starter-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattermost%2Fmattermost-plugin-starter-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattermost%2Fmattermost-plugin-starter-template/lists"}