faststore-plugin-visual-editor

Plugin to add Visual Editor endpoints to a FastStore store

📚 Documentation

• API Documentation - Complete API reference for all endpoints
• GitHub Token Generator - Tools for generating GitHub App installation tokens

🔐 GitHub Token Generation

This plugin includes tools for generating GitHub App installation tokens using the FastStore WebOps App. These tokens are required for the GitHub integration endpoints (/state and /undo) that push changes and revert commits in your repository.

Prerequisites

1. Install the FastStore WebOps App on your repository:
   • Go to FastStore WebOps App
   • Click "Install" and select your organization or repository
   • Note the Installation ID from the URL after installation: https://github.com/settings/installations/{INSTALLATION_ID}

Quick Start

1. Set up environment variables in your .env file:

GITHUB_APP_ID=123456
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
YOUR_PRIVATE_KEY_CONTENT_HERE
-----END RSA PRIVATE KEY-----"
INSTALLATION_ID=789012

2. Generate a token using the npm script:

npm run generate-token -- your-repository-name

Or use the script directly:

node scripts/generate-token.js your-repository-name

Common Use Cases

Generate token for multiple repositories

npm run generate-token -- --repos "repo1,repo2,repo3"

Generate token with custom permissions

npm run generate-token -- --permissions '{"contents":"write","issues":"read"}' my-repo

Get token in JSON format with expiration info

npm run generate-token -- --format json my-repo

Using Tokens with GitHub API Endpoints

The generated tokens are used with the GitHub integration endpoints:

Push changes to GitHub (/state endpoint)

curl -X POST http://localhost:3000/api/plugins/visual-editor/state \
  -H "Content-Type: application/json" \
  -d '{
    "token": "ghs_YOUR_TOKEN_HERE",
    "org": "your-org",
    "repo": "your-repo",
    "branchName": "feature/visual-updates",
    "changedPaths": ["src/themes/custom-theme.scss"]
  }'

Revert to a specific commit (/undo endpoint)

curl -X POST http://localhost:3000/api/plugins/visual-editor/undo \
  -H "Content-Type: application/json" \
  -d '{
    "token": "ghs_YOUR_TOKEN_HERE",
    "org": "your-org",
    "repo": "your-repo",
    "commitSha": "abc123d",
    "branchName": "main"
  }'

For detailed configuration, advanced options, and troubleshooting, see the full documentation.

Requirements

The Store must use @faststore/cli version greater than or equal to 3.86.3. Versions prior to this one will put the plugin endpoints in a different route.

Releasing new versions

To release a new version of this plugin, you bump the package version on package.json and commit with the following format:

  git commit -am "chore: release <version>"

As a convention, only add to this commit the package version updatel.

Then push the commit to the main branch.

Developing

To properly test this plugin you need to have a FastStore store. You can fork vtex-sites/faststoreqa.store to quickly set up a store. And setup the plugin by following the steps below:

1. Adding the plugin to the store's package.json

  yarn add link:../ai/faststore-plugin-visual-editor

2. Declare the plugin in the store's discovery.config.js

module.exports = {
  // ...
  plugins: [
    // other plugins,
    "@vtex/faststore-plugin-visual-editor",
  ],
};

NOTE: Changes to the plugin won't be reflected in the store until you restart the development server. This is a known issue with FastStore Plugins.