Browser plugin preview #2748

macintoshhelper · 2024-05-13T18:32:52Z

Why does this PR exist?

There is now an optional web preview mode for development, which starts an Express.js server locally with a WebSockets server. The plugin UI forwards messages between the controller and the browser version.

What does this pull request do?

Browser dev preview mode – npm run preview:browser + npm run preview:plugin
React Fast Refresh in web (HMR)
npm run build + npm run serve working
Small startup refactor to allow the plugin to run outside of the Figma sandbox/UI (entrypoint render). STARTUP handler is moved to useEffect in the startup component.

yarn build + yarn serve

yarn preview:browser

yarn preview:plugin

Testing this change

Start WebSockets server and webpack-dev-server for web preview and HMR

npm run preview:browser

Start Figma plugin dev

npm run preview:plugin

Additional Notes (if any)

May need to reload the plugin in Figma if STARTUP runs too early. Am thinking to implement a sort of dev SDK preview window in the browser, with the ability to simulate STARTUP with custom data, would need something like this to work in a Next.js preview and handle the case of having no WebSocket server or Figma plugin environment running

The preview:browser script is running an Express server with a WebSockets server, so npm run serve isn't working yet.

Plugin UI is disabled when PREVIEW_MODE/browser mode is active.

Currently Fast Refresh requires stopping the plugin preview in the command line, to prevent STARTUP from restarting the browser plugin UI.

Unrelated change, but I added dev npm packages for BundleAnalyzerPlugin and SpeedMeasurePlugin to make debugging build time/bundle size easier when needed (pass Webpack arg). These affect build times so are disabled by default.

changeset-bot · 2024-05-13T18:32:56Z

⚠️ No Changeset found

Latest commit: dce52fb

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

… options

…onnected browser dev preview)

six7

nice overall! let's hold off merging this until 2.0 is out, too much risk (and its the basis for devex anyway)

six7 · 2024-05-16T19:13:43Z

packages/tokens-studio-for-figma/src/AsyncMessageChannel.ts

@@ -26,6 +26,50 @@ export type AsyncMessageChannelHandlers = {
  >
 };

+const WEBSOCKET_SERVER_URL = 'ws://localhost:9001/ws';


could we move this to a dedicated file? as in just import those functions here - to keep things cleaner?

packages/tokens-studio-for-figma/src/app/asyncMessageHandlers/preview.tsx

packages/tokens-studio-for-figma/src/app/asyncMessageHandlers/startup.tsx

packages/tokens-studio-for-figma/src/app/index.tsx

developer-knowledgebase/async-message-channel.md

six7 · 2024-05-17T18:46:58Z

packages/tokens-studio-for-figma/src/AsyncMessageChannel.ts

-      const possiblePromise = callback(event.data.pluginMessage);
-      if (possiblePromise === false || (possiblePromise && await possiblePromise === false)) {
-        window.removeEventListener('message', listener);
+  private startWebSocketConnection() {


lots of these functions feel like we should move them to either a shared websocket file or their own files alltogether in order to improve maintainabiltiy

six7 · 2024-05-17T18:47:23Z

packages/tokens-studio-for-figma/src/AsyncMessageChannel.ts

-        const possiblePromise = callback(msg);
-        if (possiblePromise === false || (possiblePromise && await possiblePromise === false)) {
-          figma.ui.off('message', listener);
+    switch (this.environment) {


any way where we can make this function overall more readable? lots of nested ifs and switch statements 🤔

Co-authored-by: Jan Six <[email protected]>

…t now) Co-authored-by: Jan Six <[email protected]>

Co-authored-by: Jan Six <[email protected]>

packages/tokens-studio-for-figma/src/AsyncMessageChannelPreview.ts

github-actions · 2024-07-04T17:27:26Z

Commit SHA:409d986497c81348ca28f85565525d40d5506dc4

Test coverage results 🧪

Code coverage diff between base branch:release-139 and head branch: feat/browser-plugin-sync

Status	File	% Stmts	% Branch	% Funcs	% Lines
🔴	total	66.85 (-0.96)	57.86 (-0.86)	63.78 (-0.87)	67.21 (-1.01)
🔴	packages/tokens-studio-for-figma/src/AsyncMessageChannel.ts	98 (0.05)	94.11 (-2.76)	100 (0)	97.91 (0.04)
✨ 🆕	packages/tokens-studio-for-figma/src/AsyncMessageChannelPreview.ts	52.75	45.94	59.25	52
🔴	packages/tokens-studio-for-figma/src/app/components/Initiator.tsx	73.11 (-12.22)	65.78 (-4.8)	66.66 (-33.34)	72.52 (-12.41)
🔴	packages/tokens-studio-for-figma/src/app/store/updateSources.tsx	15.38 (-0.62)	27.27 (-2.73)	33.33 (0)	16 (-0.66)
🟢	packages/tokens-studio-for-figma/src/plugin/controller.ts	98.03 (0.03)	100 (0)	75 (0)	100 (0)
✨ 🆕	packages/tokens-studio-for-figma/src/plugin/asyncMessageHandlers/preview.ts	33.33	100	0	33.33

github-actions · 2024-07-04T17:27:26Z

Commit SHA:409d986497c81348ca28f85565525d40d5506dc4
Current PR reduces the test coverage percentage by 1 for some tests

…igma-plugin into feat/browser-plugin-sync

cuserox

NIIICE!

General questions for my understanding, and a couple of code simplification suggestions. Let me know what you think!

I haven't played around much with it in the browser, will add any comments if there's breakages.

cuserox · 2024-07-16T15:59:11Z

packages/tokens-studio-for-figma/package.json

@@ -11,6 +11,8 @@
    "build:dev": "cross-env NODE_ENV=development webpack --mode=development",
    "build:cy": "cross-env LAUNCHDARKLY_FLAGS=tokenThemes,gitBranchSelector,multiFileSync,tokenFlowButton yarn build",
    "start": "cross-env webpack --mode=development --watch",
+    "preview:plugin": "cross-env webpack --mode=development --PREVIEW_ENV=figma --watch",
+    "preview:browser": "cross-env WEBSOCKETS_PORT=9001 node preview-server.js & webpack-dev-server --mode=development --PREVIEW_ENV=browser",


Can we add descriptions on the README (or sibling doc in /developer-knowledgebase) on how to run the plugin in the browser?

Similar to the PR description, stating the order of commands and possible hiccups like I had 🙈

cuserox · 2024-07-16T16:47:18Z

packages/tokens-studio-for-figma/preview-server.js

+app.use(express.static(__dirname + '/dist'))
+
+app.get("/", (req, res) => {
+  // res.sendFile(path.join(__dirname, 'dist', 'index.html'));


Accidentally commented out?

cuserox · 2024-07-16T16:47:41Z

packages/tokens-studio-for-figma/preview-server.js

+  });
+
+  // send immediatly a feedback to the incoming connection
+  // ws.send('Hi there, I am a WebSocket server');


Can this be updated or removed?

cuserox · 2024-07-16T16:49:49Z

packages/tokens-studio-for-figma/src/AsyncMessageChannel.ts

@@ -142,3 +144,7 @@ export class AsyncMessageChannel {
    return promise;
  }
 }
+
+const ExportedAsyncMessageChannel = !process.env.PREVIEW_ENV ? AsyncMessageChannel : AsyncMessageChannelPreview;


Suggested change

const ExportedAsyncMessageChannel = !process.env.PREVIEW_ENV ? AsyncMessageChannel : AsyncMessageChannelPreview;

const ExportedAsyncMessageChannel = process.env.PREVIEW_ENV ? AsyncMessageChannelPreview : AsyncMessageChannel;

Could we turn the ternary around? Feels weird having a negation to start with.

Out of curiosity: what are the possible values of process.env.PREVIEW_ENV? browser | figma...?

cuserox · 2024-07-16T16:53:47Z

packages/tokens-studio-for-figma/src/AsyncMessageChannelPreview.ts

+// credits goes to https://github.com/microsoft/TypeScript/issues/23182#issuecomment-379091887
+type IsTypeOnlyObject<Obj extends Record<PropertyKey, unknown>> = [keyof Obj] extends ['type'] ? true : false;
+
+type IncomingMessageEvent<Message = unknown> = {
+  data: {
+    pluginMessage: {
+      id: string
+      message: Message
+    } | {
+      id: string
+      error: unknown
+    }
+  }
+};
+
+export type AsyncMessageChannelHandlers = {
+  [K in AsyncMessageTypes]: (incoming: AsyncMessagesMap[K]) => Promise<
+  IsTypeOnlyObject<AsyncMessageResultsMap[K]> extends true
+    ? void
+    : Omit<AsyncMessageResultsMap[K], 'type'>
+  >
+};
+
+const WEBSOCKET_SERVER_URL = 'ws://localhost:9001/ws';


These are the same types as used AsyncMessageChannel. Why not create a sub-folder containing this file + its counterpart, and perhaps a shared.ts file with the shared types / constants?

Saves a bit of duplication.

cuserox · 2024-07-16T17:25:12Z

packages/tokens-studio-for-figma/src/asyncMessageChannel.test.ts

 import { INTERNAL_THEMES_NO_GROUP } from './constants/InternalTokenGroup';
 import {
  AsyncMessageTypes, GetThemeInfoMessageResult,
 } from './types/AsyncMessages';

 describe('Testing the mock functionality of the AsyncMessageChannel', () => {
  it('should be able to communicate between UI and plugin', async () => {
-    const runAfter: (() => void)[] = [];
+    const runAfter: ((() => void) | null)[] = [];


Could save () => void) | null as a type and avoid having to update it everywhere if it changes!

cuserox · 2024-07-16T17:25:52Z

packages/tokens-studio-for-figma/webpack.config.js

-module.exports = (env, argv) => {
+const wrapper = (callback) => {
+  const measureSpeed = false;
+  if (!measureSpeed) { // Set to true to enable SpeedMeasurePlugin (breaks Figma UI build)


Could this comment be more thorough?

If not here, perhaps in a doc section to go through the why's and how's 😄

cuserox · 2024-07-16T17:26:57Z

developer-knowledgebase/async-message-channel.md

+
+```
+
+- 


Accidental bullet point

cuserox · 2024-07-16T17:27:09Z

developer-knowledgebase/async-message-channel.md

+    E -->|"ReactInstance.handle(...)"| D
+    E -->|"sendMessageToBrowser\n(ws.send(...))"| F
+    F -->|"sendMessageFromBrowser\n(ws.send(...))"| E
+```


Great diagram!!! 🎉

cuserox · 2024-07-16T17:28:05Z

developer-knowledgebase/async-message-channel.md

+Static instances of `AsyncMessageChannel` are initialised when the class is loaded:
+
+- `PluginInstance` - used from inside of `controller` entrypoint
+- `ReactInstance` - used from inside of `ui` entrypoint


Worth mentioning what inFigmaSandbox means?

github-actions · 2024-07-26T17:07:57Z

⤵️ 📦 ✨ The artifact was successfully created! Want to test it? Download it here 👀 🎁

* fix AsyncMessageChannelPreview undefined error + export WS URI * browser preview CSS file for UI fixes * create previewUtils for browser color scheme + setFigmaBrowserTheme * browser preview URL params + fullscreen/theme/action modes * two bug fixes for browser/plugin websocket preview bridge * add preview dist folder for web preview builds * [WIP] browser preview dev knowledge docs * feat(dev): request startup on browser preview page open * refactor(dev): use env vars for browser preview ws src * fix(debug): remove console.log from asyncmessagechannelpreview * fix(css): figmaloading full height css for browser preview * refactor(dev): use enums for websockets src in browser preview tsx * fix(dev): remove comments * refactor: reuse htmlClassList variable * remove unused package --------- Co-authored-by: macintoshhelper <[email protected]>

* [WIP] webpack config setup for fast refresh + websocket server * add prod/dev hmr webpack config option * render immediately and handle AsyncMessage in startup app hook * forward ui AsyncMessages to browser via WebSockets * null check sentry transaction to fix browser error * refactor AsyncMessageChannel code for browser implementation * webpack use swc-loader for browser version + speed/bundle size plugin options * prettify browser dev preview UI * enable loading screen if startup params missing (for web serve + disconnected browser dev preview) * attempt to fix webpack build for tests * add SpeedMeasurePlugin package * create AsyncMessageChannel dev docs * replace web-preview.md ASCII data flow diagram with mermaid * use radii/spacing tokens instead of px for web preview.tsx styles Co-authored-by: Jan Six <[email protected]> * remove commented out startup handler (handled in startup.tsx useEffect now) Co-authored-by: Jan Six <[email protected]> * remove commented out code Co-authored-by: Jan Six <[email protected]> * replace px values with tokens Co-authored-by: Jan Six <[email protected]> * conditional export for AsyncMessageChannel preview env * add browser preview WEBSOCKETS_PORT env * fix typescript issue with PreviewAsyncMessageChannel.isWsConnected * add test coverage for AsyncMessageChannelPreview * Browser preview debug UI (#2803) * fix AsyncMessageChannelPreview undefined error + export WS URI * browser preview CSS file for UI fixes * create previewUtils for browser color scheme + setFigmaBrowserTheme * browser preview URL params + fullscreen/theme/action modes * two bug fixes for browser/plugin websocket preview bridge * add preview dist folder for web preview builds * [WIP] browser preview dev knowledge docs * feat(dev): request startup on browser preview page open * refactor(dev): use env vars for browser preview ws src * fix(debug): remove console.log from asyncmessagechannelpreview * fix(css): figmaloading full height css for browser preview * refactor(dev): use enums for websockets src in browser preview tsx * fix(dev): remove comments * refactor: reuse htmlClassList variable * remove unused package --------- Co-authored-by: macintoshhelper <[email protected]> --------- Co-authored-by: macintoshhelper <[email protected]> Co-authored-by: Jan Six <[email protected]>

* Browser plugin preview (#2748) * [WIP] webpack config setup for fast refresh + websocket server * add prod/dev hmr webpack config option * render immediately and handle AsyncMessage in startup app hook * forward ui AsyncMessages to browser via WebSockets * null check sentry transaction to fix browser error * refactor AsyncMessageChannel code for browser implementation * webpack use swc-loader for browser version + speed/bundle size plugin options * prettify browser dev preview UI * enable loading screen if startup params missing (for web serve + disconnected browser dev preview) * attempt to fix webpack build for tests * add SpeedMeasurePlugin package * create AsyncMessageChannel dev docs * replace web-preview.md ASCII data flow diagram with mermaid * use radii/spacing tokens instead of px for web preview.tsx styles Co-authored-by: Jan Six <[email protected]> * remove commented out startup handler (handled in startup.tsx useEffect now) Co-authored-by: Jan Six <[email protected]> * remove commented out code Co-authored-by: Jan Six <[email protected]> * replace px values with tokens Co-authored-by: Jan Six <[email protected]> * conditional export for AsyncMessageChannel preview env * add browser preview WEBSOCKETS_PORT env * fix typescript issue with PreviewAsyncMessageChannel.isWsConnected * add test coverage for AsyncMessageChannelPreview * Browser preview debug UI (#2803) * fix AsyncMessageChannelPreview undefined error + export WS URI * browser preview CSS file for UI fixes * create previewUtils for browser color scheme + setFigmaBrowserTheme * browser preview URL params + fullscreen/theme/action modes * two bug fixes for browser/plugin websocket preview bridge * add preview dist folder for web preview builds * [WIP] browser preview dev knowledge docs * feat(dev): request startup on browser preview page open * refactor(dev): use env vars for browser preview ws src * fix(debug): remove console.log from asyncmessagechannelpreview * fix(css): figmaloading full height css for browser preview * refactor(dev): use enums for websockets src in browser preview tsx * fix(dev): remove comments * refactor: reuse htmlClassList variable * remove unused package --------- Co-authored-by: macintoshhelper <[email protected]> --------- Co-authored-by: macintoshhelper <[email protected]> Co-authored-by: Jan Six <[email protected]> * Browser plugin preview (#2748) * [WIP] webpack config setup for fast refresh + websocket server * add prod/dev hmr webpack config option * render immediately and handle AsyncMessage in startup app hook * forward ui AsyncMessages to browser via WebSockets * null check sentry transaction to fix browser error * refactor AsyncMessageChannel code for browser implementation * webpack use swc-loader for browser version + speed/bundle size plugin options * prettify browser dev preview UI * enable loading screen if startup params missing (for web serve + disconnected browser dev preview) * attempt to fix webpack build for tests * add SpeedMeasurePlugin package * create AsyncMessageChannel dev docs * replace web-preview.md ASCII data flow diagram with mermaid * use radii/spacing tokens instead of px for web preview.tsx styles Co-authored-by: Jan Six <[email protected]> * remove commented out startup handler (handled in startup.tsx useEffect now) Co-authored-by: Jan Six <[email protected]> * remove commented out code Co-authored-by: Jan Six <[email protected]> * replace px values with tokens Co-authored-by: Jan Six <[email protected]> * conditional export for AsyncMessageChannel preview env * add browser preview WEBSOCKETS_PORT env * fix typescript issue with PreviewAsyncMessageChannel.isWsConnected * add test coverage for AsyncMessageChannelPreview * Browser preview debug UI (#2803) * fix AsyncMessageChannelPreview undefined error + export WS URI * browser preview CSS file for UI fixes * create previewUtils for browser color scheme + setFigmaBrowserTheme * browser preview URL params + fullscreen/theme/action modes * two bug fixes for browser/plugin websocket preview bridge * add preview dist folder for web preview builds * [WIP] browser preview dev knowledge docs * feat(dev): request startup on browser preview page open * refactor(dev): use env vars for browser preview ws src * fix(debug): remove console.log from asyncmessagechannelpreview * fix(css): figmaloading full height css for browser preview * refactor(dev): use enums for websockets src in browser preview tsx * fix(dev): remove comments * refactor: reuse htmlClassList variable * remove unused package --------- Co-authored-by: macintoshhelper <[email protected]> --------- Co-authored-by: macintoshhelper <[email protected]> Co-authored-by: Jan Six <[email protected]> * update web preview script docs * fix: updateStyles error from merge conflict * lint: remove comments and cleanup * fix: language switch on startup for new preview startup * lint: remove more comments from preview files * lint: fix indentation error because of prettier conflict --------- Co-authored-by: macintoshhelper <[email protected]> Co-authored-by: Jan Six <[email protected]>

macintoshhelper added 5 commits May 7, 2024 12:35

[WIP] webpack config setup for fast refresh + websocket server

ef182ee

add prod/dev hmr webpack config option

be823c3

render immediately and handle AsyncMessage in startup app hook

ffb544c

forward ui AsyncMessages to browser via WebSockets

3a8681c

null check sentry transaction to fix browser error

9502583

macintoshhelper and others added 5 commits May 15, 2024 17:54

refactor AsyncMessageChannel code for browser implementation

748baff

webpack use swc-loader for browser version + speed/bundle size plugin…

06121cb

… options

prettify browser dev preview UI

1fab0e3

enable loading screen if startup params missing (for web serve + disc…

00411ef

…onnected browser dev preview)

Merge branch 'release-139' into feat/browser-plugin-sync

ef5a69d

macintoshhelper marked this pull request as ready for review May 16, 2024 12:57

macintoshhelper added 3 commits May 16, 2024 16:35

attempt to fix webpack build for tests

b29a131

add SpeedMeasurePlugin package

ece5852

create AsyncMessageChannel dev docs

8fa364f

six7 requested changes May 17, 2024

View reviewed changes

macintoshhelper and others added 7 commits May 20, 2024 12:24

replace web-preview.md ASCII data flow diagram with mermaid

0817418

Merge branch 'release-139' into feat/browser-plugin-sync

f4783e5

use radii/spacing tokens instead of px for web preview.tsx styles

261d19d

Co-authored-by: Jan Six <[email protected]>

remove commented out startup handler (handled in startup.tsx useEffec…

ec92b4d

…t now) Co-authored-by: Jan Six <[email protected]>

remove commented out code

c5343de

Co-authored-by: Jan Six <[email protected]>

replace px values with tokens

d894870

Co-authored-by: Jan Six <[email protected]>

conditional export for AsyncMessageChannel preview env

bf1c02c

macintoshhelper mentioned this pull request May 28, 2024

Visual regression testing #2799

Open

macintoshhelper and others added 3 commits May 29, 2024 18:56

add browser preview WEBSOCKETS_PORT env

a2da16f

Merge branch 'release-139' into feat/browser-plugin-sync

178b5b8

Merge branch 'release-139' into feat/browser-plugin-sync

e0c8b82

github-advanced-security bot found potential problems Jul 3, 2024

View reviewed changes

packages/tokens-studio-for-figma/src/AsyncMessageChannelPreview.ts Dismissed Show dismissed Hide dismissed

macintoshhelper and others added 2 commits July 3, 2024 16:05

fix typescript issue with PreviewAsyncMessageChannel.isWsConnected

a16c919

Merge branch 'release-139' into feat/browser-plugin-sync

baa31ef

macintoshhelper added 3 commits July 5, 2024 15:47

Merge branch 'release-139' into feat/browser-plugin-sync

b6617cb

Merge branch 'feat/browser-plugin-sync' of github.com:tokens-studio/f…

abb4365

…igma-plugin into feat/browser-plugin-sync

add test coverage for AsyncMessageChannelPreview

d8c9e36

cuserox assigned macintoshhelper Jul 15, 2024

cuserox approved these changes Jul 16, 2024

View reviewed changes

Merge branch 'release-139' into feat/browser-plugin-sync

4e1e315

six7 changed the base branch from release-139 to dx July 26, 2024 17:52

six7 merged commit 90906fd into dx Jul 26, 2024
7 of 8 checks passed

six7 deleted the feat/browser-plugin-sync branch July 26, 2024 18:06

macintoshhelper mentioned this pull request Oct 21, 2024

DX: Browser plugin preview #3184

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Browser plugin preview #2748

Browser plugin preview #2748

macintoshhelper commented May 13, 2024 •

edited

Loading

changeset-bot bot commented May 13, 2024 •

edited

Loading

six7 left a comment

six7 May 16, 2024

six7 May 17, 2024

six7 May 17, 2024

github-actions bot commented Jul 4, 2024 •

edited

Loading

github-actions bot commented Jul 4, 2024 •

edited

Loading

cuserox left a comment

cuserox Jul 16, 2024

cuserox Jul 16, 2024

cuserox Jul 16, 2024

cuserox Jul 16, 2024

cuserox Jul 16, 2024

cuserox Jul 16, 2024

cuserox Jul 16, 2024

cuserox Jul 16, 2024

cuserox Jul 16, 2024

cuserox Jul 16, 2024

cuserox Jul 16, 2024

github-actions bot commented Jul 26, 2024 •

edited

Loading

	const ExportedAsyncMessageChannel = !process.env.PREVIEW_ENV ? AsyncMessageChannel : AsyncMessageChannelPreview;
	const ExportedAsyncMessageChannel = process.env.PREVIEW_ENV ? AsyncMessageChannelPreview : AsyncMessageChannel;


		```

		-

Browser plugin preview #2748

Browser plugin preview #2748

Conversation

macintoshhelper commented May 13, 2024 • edited Loading

Why does this PR exist?

What does this pull request do?

Testing this change

Additional Notes (if any)

changeset-bot bot commented May 13, 2024 • edited Loading

⚠️ No Changeset found

six7 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Jul 4, 2024 • edited Loading

Test coverage results 🧪

github-actions bot commented Jul 4, 2024 • edited Loading

cuserox left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Jul 26, 2024 • edited Loading

macintoshhelper commented May 13, 2024 •

edited

Loading

changeset-bot bot commented May 13, 2024 •

edited

Loading

github-actions bot commented Jul 4, 2024 •

edited

Loading

github-actions bot commented Jul 4, 2024 •

edited

Loading

github-actions bot commented Jul 26, 2024 •

edited

Loading