BREAKING NEWS: How to Create Your First New Sidebar Chrome Extension MV3 for Beginner Developer

[Stefan Van Damme]

Hi everyone,

You can now create a sidebar, also known as a side panel, in Chrome Canary version 114.0.5735.0 or higher. In my latest blog post, I will guide you through the process of creating your first Chrome extension's side panel, from setting up your development environment to coding your extension. This tutorial will help you create a useful and functional Chrome extension in no time! So, let's get started!

https://www.stefanvd.net/blog/2023/05/06/how-to-create-a-sidebar-chrome-extension-mv3/

Example code for all browser extensions (Chrome, Opera, Firefox, Naver Whale):

https://github.com/stefanvd/Browser-Extensions/tree/master/Note-Sidebar

The first published Note Sidebar Chrome extension on the Chrome Web Store:

https://chrome.google.com/webstore/detail/note-sidebar/emiochiflnnegkecnjndifbobmbepdne

If you have any inquiries or suggestions, please feel free to share them with me.

Thanks,
Stefan vd

[Dustin Byers]

This seems awesome! Does it have access to the same context as a content script? If it can use all the chrome apis, this sounds fantastic.

[Stefan Van Damme]

Hi Dustin,

The Chrome side panel is a page on the right side that appears the same way as a popup panel when you click on the browser action icon. This means that you can use all the same Chrome APIs and functionality within your popup page. Since it is a page, you can apply your own script to the HTML page. Try the example to test it out.

For more information, please refer to this newly published API page:

https://developer.chrome.com/docs/extensions/reference/sidePanel/#overview

Thanks,
Stefan vd

[Jackie Han]

Great, I can imagine some usage scenarios. Since the popup closes automatically, sidepanel is suitable for scenarios where popup need to be kept open all the time.

Hi Stefan, I have a doubt about "side_panel" in manifest.json. In your manifest:

  "side_panel": {
    "default_icon": {
      "16": "images/icon16.png",
      "32": "images/icon32.png"
    },
    "default_title": "__MSG_name__",
    "default_path": "panel.html",
    "openPanelOnActionClick": true

  },

Are you sure these subkeys in "side_panel" can work? 

• API doc: https://developer.chrome.com/docs/extensions/reference/sidePanel/
• IDL: https://source.chromium.org/chromium/chromium/src/+/main:chrome/common/extensions/api/side_panel.idl

Above links show that only the key "default_path" is available in "side_panel".

--
You received this message because you are subscribed to the Google Groups "Chromium Extensions" group.
To unsubscribe from this group and stop receiving emails from it, send an email to chromium-extens...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/chromium-extensions/73238b93-0817-498a-8521-b0972e0b72ean%40chromium.org.

[Stefan Van Damme]

Hi Jackie,

You bring up a good point regarding the 'side_panel' subkeys in the manifest.json file. It looks incorrect, but I tested it on that day and it worked on my Chrome Canary build. I tested and confirmed that it works on Chrome Canary version 114.0.5735.0.
Upon reviewing it, I noticed that "default_icon" is not needed for Chrome Canary. However, "default_title" is needed but is placed under "action".

"side_panel": {

"default_path": "panel.html"

},

"action": {

"default_title": "Click to open panel"

},

In other web browsers, the "default_icon" and "default_title" are necessary to obtain the sidebar icon. I have updated this in the blog post.

Thank you for bringing this to my attention. Please let me know if you have any further questions!

Thanks,
Stefan vd

[Jackie Han]

I use Chrome Canary 115.0.5755.0

// manifest.json

  "side_panel": {
    "openPanelOnActionClick": true, // this doesn't work
    "default_path": "sidepanel.html"
  },

In my test, "openPanelOnActionClick"  doesn't work in manifest. I see you have removed it now.

I also found a confusing behavior.

// sw.js

chrome.runtime.onInstalled.addListener(e => {
  chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});

Above code work. but when I remove the setPanelBehavior() line of code and click the reload button in chrome://extensions/ , Chrome still opens the side panel by clicking the extension icon (a chrome bug?). If I remove the unpacked extension entirely and re-add it, I see it can't open sidepanel now (back to default behavior). If you don't want to remove the unpacked extension entirely, you need to explicitly set `openPanelOnActionClick` to false and click the reload button.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/chromium-extensions/95667b23-4aed-4f38-811a-55d8bf839028n%40chromium.org.

[Robbi]

I'm not very enthusiastic about it because I feel like I'm seeing a movie I've already seen.

I expect, as with action.openPopup, to see this sidebar work in fits and starts. I mean with one build yes and with the next no and so on...

For my part I will not experiment and publish anything until I see the API in the stable channel.

On the other hand, I am currently using this feature in 2 extensions adapted for other browsers.

After reading Stefan's tutorial, my contribution to this post is merely to highlight (for those who don't already know) that:

1. The sidebar can also be used with manifest V2 in Firefox and Opera.
2. Both Naver and Opera sidebar contents are not cleared when the sidebar is closed. (reopening it immediately afterwards we will in fact find the same contents). From this point of view the sidebar in Chrome and Firefox behaves like a (browser)action popup.
   
3. With Naver you can choose sidebar or action popup, but not both.
   

In conclusion, from my point of view I consider this feature still "unrape"

[Stefan Van Damme]

Hi Jackie,

|| In my test, "openPanelOnActionClick"  doesn't work in manifest. 

I updated my sample code. As there may be a bug present. When I tested it, it seemed to work. If this API doesn't work, Google Chrome should consider adding it to the manifest, as adding it to the service worker is not ideal. When compared with other web browsers, it creates development inconsistencies and a huge mess, which does not align with the W3 WebExtension view.

|| Above code work. but when I remove the setPanelBehavior() line of code and click the reload button in chrome://extensions/ , Chrome still opens the side panel by clicking the extension icon (a chrome bug?). If I remove the unpacked extension entirely and re-add it, I see it can't open sidepanel now (back to default behavior). If you don't want to remove the unpacked extension entirely, you need to explicitly set `openPanelOnActionClick` to false and click the reload button.

Yes, saw this issue too, possibly a bug in Chrome.

Thanks,
Stefan vd

[Stefan Van Damme]

Hi Robbi,

Thank you for sharing your thoughts on the Chromium extension post.

|| For my part I will not experiment and publish anything until I see the API in the stable channel.

Yes, it is also wise to wait until the API is in the stable channel before experimenting and publishing anything. But share this news for the early adopter developers that are eager to test this.

|| 1. The sidebar can also be used with manifest V2 in Firefox and Opera.

I also noted that, and there is here already a misalignment in the W3 extension view. Different code and no harmony in the extension development. When I create the sample on my GitHub, I must create just 4 separate folders for each web browser. It should be one.

https://github.com/stefanvd/Browser-Extensions/tree/master/Note-Sidebar

|| 2. Both Naver and Opera sidebar contents are not cleared when the sidebar is closed. (reopening it immediately afterwards we will in fact find the same contents). From this point of view the sidebar in Chrome and Firefox behaves like a (browser)action popup.

In Google Chrome, the side panel stays open even when you navigate to other tab pages or open a new page. You can close the panel by clicking on the X icon or going back to the action button in the toolbar.

|| 3. With Naver you can choose sidebar or action popup, but not both.

That is also for Google Chrome, I did the test with this code:

"side_panel": {
    "default_path": "panel.html"
  },
  "action": {

    "default_title": "__MSG_name__",
    "default_icon": {            
      "16": "images/icon16.png",
      "24": "images/icon24.png",
      "32": "images/icon32.png"
    },
    "default_popup": "panel.html"  
  },

And here it will not open the popup panel but the side panel.

Thanks,
Stefan vd

[Simeon Vincent]

|| 1. The sidebar can also be used with manifest V2 in Firefox and Opera.
I also noted that, and there is here already a misalignment in the W3 extension view. Different code and no harmony in the extension development. When I create the sample on my GitHub, I must create just 4 separate folders for each web browser. It should be one.

Figured I should pop in to share a bit more context from the WECG. As you indicated, the group is trying to work towards a consistent browser extension platform that works across browsers. At the same time, during the initial chartering process browser vendors expressed a strong desire for autonomy and the ability to go down separate paths.

In the case of the Sidepanel API, the Chrome team was concerned that using an existing API would send the wrong signal to developers. If Chrome adopted Sidebar, developers would expect the Chrome feature to use the same API and behaviors as Firefox. Since Chrome's sidepanel is a relatively new feature, they wanted the freedom to figure out what capabilities and behaviors were right for Chrome. I should also note that this doesn't rule out the possibility of future alignment.

IMO how we approach this kind of consolidation is part of a larger conversation about future manifest version bumps and breaking changes. I have some thoughts around this that I'm hoping to explore in blog posts Soon™.

Simeon - @dotproto

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/chromium-extensions/138b1180-38b2-4c69-800b-40954eb20bc2n%40chromium.org.

[Stefan Van Damme]

Hi everyone,

I have noticed divisive issues arise in the Google Chrome web browser. The lack of compatibility with other web browsers creates a mess in the API use. If each web browser were to develop their own API, it would go against the goal of the W3 to bring harmony to browser extension development. The aim should be to have one API that works for all web browsers. For example, the "menu" feature is not accepted for Google Chrome (but "menus" support in Safari, and Firefox web browser), and now the "sidePanel" has a different API than the other working API "sidebar", which creates confusion and mismatched behavior. If other web browsers were to create their "sidePanel" API too, it would lead to further confusion.

I support the upcoming Manifest V4, which will provide a common sense and consistent approach for all web browsers, with the same API for all, and without any gray zone.

Thanks,
Stefan vd

[Uladzimir Yankovich]

Colleagues, we started experimenting with the Sidepanel API, and so far, one of the main difficulties is determining when our app is hidden (closes) in the side panel.

So far, we've settled on polling clients.matchAll() every second, but I don't think this is a good solution.

It seems to me that the Sidepanel API is missing at least two events: Show and Hide.

[Robbi]

Why polling every second? At most you should poll every time you need to know if sidePanel is open or not. Don't you think?

I guess you could also set a storage.session item to save the sidePanel state and read that item evert time you need

[Uladzimir Yankovich]

Yes, I understand how do I know if my panel is currently shown. But this does not solve my problem - I need to immediately respond on the side of SW and other contents to close my side panel. And while I have not come up with anything better than every second poll clients.matchAll().

[Robbi]

Navel Whale has 2 method to show and hide that panel, whereas Opera has 2 event for Blur and Focus.

As I've already stated: "too many inconsistencies among vendors and (this time) I have no intention of being the lab rat of their their experiments"

Try to post a few lines of code, it could be me or someone else to help you.

[Uladzimir Yankovich]

Robbi, I want to thank you so much for your participation. Unfortunately, there is no code yet, there is only a task, and we are thinking of the best design for its solution.

Let's present such intros. There is a floating button on the page, by clicking on which part of the content from the page is transferred to the side panel. And I want this floating button only to show up when my sidebar is visible. And if the panel is closed, the floating button is immediately hidden.

I understand that we can approach the other side and consider changing the requirements for the product. But suppose this is not possible.

In this case, I see a possible solution: receiving an event from the sidepanel API (which doesn't exist yet) or polling clients.matchAll() every second.

--

Uladzimir Yankovich,

Founder @ Manganum (manganum.app).

[Oliver Dunk]

Hi all,

I've been meaning to jump in here now things are less busy with I/O! First off, great work on that blog post Stefan - really appreciate you writing up such a useful summary for everyone and appreciate the feedback in it :)

Going to try and reply to some of the questions that have come up...

Above code work. but when I remove the setPanelBehavior() line of code and click the reload button in chrome://extensions/ , Chrome still opens the side panel by clicking the extension icon (a chrome bug?). If I remove the unpacked extension entirely and re-add it, I see it can't open sidepanel now (back to default behavior). If you don't want to remove the unpacked extension entirely, you need to explicitly set `openPanelOnActionClick` to false and click the reload button.

This sounds like the intended behaviour to me - it's something which persists across browser restarts, which is why you can call it once in the onInstalled listener. You can think of it similar to setting a keyboard shortcut from chrome://extensions/shortcuts for example, which also persists.

In my test, "openPanelOnActionClick"  doesn't work in manifest. 

At the moment, we only support setting this from the API. We actually had a lot of discussion there, and can see benefits to both. But there are also some trickier things to figure out - like does this go under the `action` or `side_panel`  manifest key for example? Those are of course solvable and I definitely appreciate the feedback (we may be able to add something like this in the future) - but we decided that we wanted to prioritise adding an API first as that gives the most flexibility. You could change the setting based on a user settings page, for example.

I also noted that, and there is here already a misalignment in the W3 extension view. Different code and no harmony in the extension development. When I create the sample on my GitHub, I must create just 4 separate folders for each web browser. It should be one.

I definitely appreciate all of the feedback about the fact that we don't have the same API across browsers yet. As someone who has been attending the community group long before I joined Google, I definitely want us to keep working on that. As Simeon pointed out, the group does leave some room for autonomy, but I do think we should use that sparingly :)

Colleagues, we started experimenting with the Sidepanel API, and so far, one of the main difficulties is determining when our app is hidden (closes) in the side panel.

Interesting, that's not something I'd thought about before. I haven't tried this, but could you open a message port between the side panel and the content script? You could then listen for the disconnect event and use that as your close signal.

I can also pass on the feedback - I think it's an interesting problem.

Oliver Dunk | DevRel, Chrome Extensions | https://developer.chrome.com/ | London, GB

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/chromium-extensions/e3663b32-47e6-40b1-95f8-22338fe9c8d9n%40chromium.org.

[Jackie Han]

one of the main difficulties is determining when our app is hidden (closes) in the side panel.

Because web page is at the left, and side panel is at the right,

1. when side panel is open, window.innerWidth < window.outerWidth

2. when side panel is closed, window.innerWidth == window.outerWidth

Does this solve your problem?

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/chromium-extensions/e4a34bda-fb5a-4afc-b01c-8eeb75740bb8n%40chromium.org.

[Robbi]

Have you tried from the sideBar to open a communication channel that will be hooked \ used by the SW (onConnect) for the exchange of messages?
The SW will also be the repeater from\to any other page.
From the same service worker with the onDisconnect event you should understand exactly when the sideBar will be closed.
However, the channel will not remain open forever so before the SW is unloaded you will have to message something (in fact this too can be considered a polling but with a lower frequency i.e every 25 seconds)
I haven't tested what I've just written but it seems feasible to me.

[Jackie Han]

My above solution combined with window.addEventListener("resize", callback) should detect whether the side panel is open.

But the side panel is open doesn't mean your extension's side panel is loaded. If users click Chrome's sidepanel button (not your extension action icon), your extension's side panel may not be loaded, e.g. it shows the built-in "Reading List" panel.

Maybe the following api is useful:

chrome.sidePanel.onOpen.addListener()

chrome.sidePanel.onClosed.addListener()

or combine them into one event 

chrome.sidePanel.onStateChanged.addListener()

test whether the side panel is open:

chrome.runtime.getContexts({contextTypes: ["SIDE_PANEL"]});

[Uladzimir Yankovich]

Guys, thanks for your input.

We thought about using a connection and an onDisconnect event. But, firstly, from our past negative experiences, I do not trust this method. Second, it doesn't fit because the user can switch the app in Chrome's sidebar, in which case the connection won't be closed.

The screen-width-tracking option also fails in the case of changing the active sidebar application. And besides that, it is not possible in combination with a new tab page, downloads page, history, and so on.

It looks like we'll have to stop at the regular poll for now.

[Uladzimir Yankovich]

@Oliver, I will be glad if you deliver the thoughts from this thread to the decision-makers.

Also, I would like to talk about one more improvement to the Sidepanel API here. It seems that for many developers and users, it would be convenient if the extension could explicitly pass parameters such as min / max-width to the panel creation parameters.

Historically, extensions have lived in limited surfaces. For example, an extension popup with a static size. And it seems that the inability to limit the width of the side panel will result in difficulties for developers and bad UX for users.

[Robbi]

Stop trying instead and let that all testing stage is made by who is paid to do that.

The latest runner to reach this "milestone" is Chrome, so Chrome has the opportunity to "get inspired" by its competitors.

He can take the best and leave the worst of the work done so far, or screw it up (as he sometimes does)

[Oliver Dunk]

Uladzimir - thanks for all of the feedback!

 

We thought about using a connection and an onDisconnect event. But, firstly, from our past negative experiences, I do not trust this method. Second, it doesn't fit because the user can switch the app in Chrome's sidebar, in which case the connection won't be closed.

Do you mind elaborating on the experiences you've had there? I think it should be fairly reliable. Good call out on switching between extensions though - I'm wondering if we should fire the "pagehide" event perhaps. It makes sense to me but I hesitate slightly because I know it has a very specific meaning on the web and we likely want to respect that. I don't know enough about it to feel confident making a call there.

@Oliver, I will be glad if you deliver the thoughts from this thread to the decision-makers.

Absolutely! I've already been passing comments from this thread, the I/O thread and other places like Twitter along, and I'll continue to do that. This is only the first release of the API and I'm sure we will be making improvements over time.

Also, I would like to talk about one more improvement to the Sidepanel API here. It seems that for many developers and users, it would be convenient if the extension could explicitly pass parameters such as min / max-width to the panel creation parameters.

Interesting. Do you have any thoughts on how this would work with other Side Panels? I imagine it would just reduce in size whenever you switch to the extension? 

Robbi - I'm not sure exactly what you were trying to say but please remember to keep things respectful. If you have specific feedback about the API or how it was launched then we'd love to hear it. We specifically don't ship with everything on day one, though, because it's nice to see how an API is used and base decisions on that.

Oliver Dunk | DevRel, Chrome Extensions | https://developer.chrome.com/ | London, GB

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/chromium-extensions/14973d74-a5af-48ae-b0d7-86e780451d66n%40chromium.org.

[Jackie Han]

It looks like we are concerned about: 

1. Whether the sidepanel is open and the extension side panel is loaded.

This can be resolved by Clients API for now or runtime.getContexts({contextTypes: ["SIDE_PANEL"]}) (in the future).

2. Whether this extension's side panel is active, not other extensions or built-in panels. This can be resolved by Page Visibility API inside the side panel:

document.visibilityState // 'visible' or 'hidden'

document.hidden // true or false

document.addEventListener("visibilitychange", listener); 

[Oliver Dunk]

Oh nice Jackie, that seems to do the trick!

I wasn't aware of that so thanks for pointing it out.

Oliver Dunk | DevRel, Chrome Extensions | https://developer.chrome.com/ | London, GB

[Uladzimir Yankovich]

Hm, it didn't really bother me 🤣

The Clients API already perfectly returns both the fact that the panel is loaded and whether it is currently visible - https://gang.manganum.app/QzrnJQNJ. We have all the tools to find out the current state of the panel. But we don't have other tools besides polling to instantly respond to their changes.

[Jackie Han]

Yes, Client API already contains WindowClient.visibilityState.

But we don't have other tools besides polling to instantly respond to their changes.

In my previous comment, I suggested a chrome.sidePanel.onStateChanged.addListener().

[Uladzimir Yankovich]

Great discussion 🤗

1. About the way to track the closing of the sidebar through onDisconect.
— I don't trust him because I don't trust the SW 🥹
— It does not solve the problem of switching between applications.

2. About the sidebar show/hide event
— I think we synchronized quite well. I like Jackie's idea with chrome.sidePanel.onStateChanged.addListener().

3. NEW! About why we cannot stop at the Client API.
— Client API does not return the most important sidebar parameter - WindowID.

3.1. Why is WindowID so important when working with sidebars?
— Because the sidebar is actually unique within the window. And therefore, all events and methods for interacting with panels must support this parameter for the convenience of working with this API. Here is an example, https://gang.manganum.app/yy78rBcv - what is what is completely incomprehensible.

4. About the ability for extensions to set limits on the width of their sidebar.
— Yes, if different sidebar applications have different forced width settings, then when switching between them, the width of the panel will change. And while this may not seem like the best UX, it is much better than broken layout and manually changing the width for users.

[Uladzimir Yankovich]

We've run into another problem. Some of our functions are implemented through iFrame. And to communicate with our frames, we used Chrome.tabs.sendmessage, now this is not possible, and messages from Chrome.runtime are not visible inside the frames 😭

[Oliver Dunk]

Hmm, interesting. I can't think of a simple solution today but I wonder if runtime.getContexts() would help if we introduce content scripts and the ability to message context IDs in the future. I think you've seen that API already, but if not: https://groups.google.com/a/chromium.org/g/chromium-extensions/c/9nzzbr0kErc

Short term, this may be another case where ports help and you could open a port from the iframe to the service worker?

Oliver Dunk | DevRel, Chrome Extensions | https://developer.chrome.com/ | London, GB

[Uladzimir Yankovich]

Yes, we did. But this is a significant complication of all existing logic. I hope that in the near future chrome.runtime.getContexts will make our life easier 🥹

[Uladzimir Yankovich]

The inability to call chrome.windows.getCurrent from the Chrome side panel also makes development difficult.

Does anyone have any ideas for workarounds?

[wOxxOm]

https://crbug.com/1446067 suggests tabId. You can suggest adding windowId as well but maybe it's redundant because it can be extracted via chrome.tabs.get(tabId)

The workaround is to specify the data as URL query parameters of the panel:

chrome.sidePanel.setOptions({
  tabId: tab.id,
  path: 'panel.html?' + new URLSearchParams({
    tabId: tab.id,
    winId: tab.windowId,
  }),
});

Then read it inside the panel:

const { tabId, winId } = Object.fromEntries(new URLSearchParams(location.search));