Add Mac Store guide by andrewitsover · Pull Request #251 · electron-forge/electron-forge-docs

andrewitsover · 2025-12-15T05:08:25Z

A step-by-step guide on how to distribute your app inside or outside of the Mac App Store, and to the Windows store.

Kilian · 2025-12-17T08:01:11Z

guides/code-signing/code-signing-macos.md

+- Developer ID Application
+- Developer ID Installer
+
+All of these certificates should be created through Xcode after you have signed up for an Apple Developer Account. If you have created them any other way, you will have to delete them.


I don't think this is true, you can create them on the developer.apple.com website, download and install them. The removed link has information on that, so it's worth keeping.

When I tried this, it did not work. The only way that worked was via Xcode.

Kilian · 2025-12-17T08:02:20Z

guides/code-signing/code-signing-macos.md

+
+Once you have created the certificates, you need to go to your Apple Developer Account and create provisioning profiles. If you are submiting your app to the app store, you will need a development profile and a distribution profile. If you are submiting it outside of the app store, you will need a profile for the ```Developer ID Application``` certificate.
+
+You need to download these after creating them and double clicking them to install them on your computer. Not all of them can be installed locally, but just double-click on them anyway.


I don't think guides should tell readers to do something "anyway". Either its required, or we can leave it out.

Yes, I can't remember which ones do and don't need double clicking. If you double click one of them, it tells you it can't be installed or something like that.

Kilian · 2025-12-17T08:05:00Z

guides/code-signing/code-signing-macos.md

-};
+```optionsForFile```: for distribution outside of the app store, you may be able to rely on the defaults if you app doesn't need any extra entitlements. For the app store, you will definitely need to provide this.
+
+You need to add logic to determine which set of entitlements to use. If you specify more entitlements then your app uses, it will probably be rejected by the review process.


- You need to add logic to determine which set of entitlements to use. If you specify more entitlements then your app uses, it will probably be rejected by the review process. + Your list of entitlements should contain only the ones your application needs. Adding extraneous entitlements could be cause for rejection during the review process.

Kilian · 2025-12-17T08:05:44Z

guides/code-signing/code-signing-macos.md

 module.exports = {
  packagerConfig: {
-    osxSign: {} // object must exist even if empty
+    osxSign: {


Is there any reason not to recommend the empty configuration object as the default anymore?

I don't think there is a case where it would work with no options.

Just tested myself on electron/minimal-repro and I can confirm that osxSign: {} works for me after checking the output with codesign -dv.

Mmm.... I don't think it is that simple. Anyway, there would need to be some kind of examples, which is the foundation of any good documentation. Leaving it empty and simply describing the fields is pointless. Either way, I will make the edits I agree with and you can do the rest as you see fit. I will do that now.

Kilian · 2025-12-17T08:07:07Z

guides/code-signing/code-signing-macos.md

+| `appleId`         | string | Usually the email address you used to create your Apple Developer account.                                                                                                                                                         |
+| `appleIdPassword` | string | A one-time password that can be create via the Apple Developer website.                                                                                                                                                                                       |
+| `teamId`          | string | The Apple Team ID you want to notarize under. It is the set of characters inside the brackets at the end of your identity name. |


The old descriptions were more helpful and used the terminology as used by Apple.

Not from my experience. As the documentation was wrong in many places, I can't see how the author could know which is the best or not best. It wasn't possible to submit to the MAS using the documentation.

Kilian · 2025-12-17T08:09:56Z

guides/code-signing/code-signing-macos.md

  packagerConfig: {
    // ...
    osxNotarize: {
+      tool: 'notarytool',


this the default so should be left out

Kilian · 2025-12-17T08:09:57Z

guides/code-signing/code-signing-macos.md

  packagerConfig: {
    osxSign: {},
    osxNotarize: {
+      tool: 'notarytool',


this the default so should be left out

Kilian · 2025-12-17T08:10:45Z

guides/mac-store.md

+
+# App Store
+
+Follow the documentation on how to add Electron Forge to your project. This is fairly straight-forward, so I won't go into it.


Tutorials should avoid calling things "straight-forward", "easy" et cetera.

Yeah, I have missed some casual language as it is adapted from an informal guide.

Kilian · 2025-12-17T08:11:52Z

guides/mac-store.md

+ ```
+{% endcode %}
+
+```appBundleId```: At some point, you need to sign up for an Apple Developer Account and create an app. This is where you create a bundle Id that you then provide to Forge in this field.


At some point, you need to sign up for an Apple Developer Account and create an app.

Is this helpful information to explain appBundleId?

Kilian · 2025-12-17T08:13:12Z

guides/mac-store.md

+
+After the packager configuration, there is the ```maker``` configuration and some types of configuration that you can just leave as they are unless you have a use for them.
+
+I don't think you need any makers just for testing. Maybe add the ```zip``` maker if nothing is created. For distribution on the Mac store you need to create a ```pkg``` file.


a guide should not have "I don't think you need" sentences. Guides are authoritative.

Yeah, I have missed some casual language as it is adapted from an informal guide.

Kilian · 2025-12-17T08:13:47Z

guides/mac-store.md

+
+## Package Configuration
+
+Inside your ```package.json``` you might need to add a ```productName``` field. The scripts mentioned below can help you bundle and package your code.


might, or have to? Guides should work to remove ambiguity in the process.

It don't know whether it is needed or not. It was written a while ago when I was making an app. Unless somebody knows, I would go with it being required.

Kilian · 2025-12-17T08:14:30Z

guides/mac-store.md

+```
+{% endcode %}
+
+```npm run mas``` will create a ```pkg``` file for distribution inside the app store, assuming you have used the appropriate forge configuration. For testing, you don't need to use any of the ```makers``` so you can just use ```npm run package```.


Try to avoid telling readers they can "just" do something. Remove the word just

Kilian · 2025-12-17T08:14:49Z

guides/mac-store.md

+
+## Testing and Submission
+
+To test your application before submitting it to the app store, you need to make sure you are actually running inside an app store sandbox, and not just running like a normal mac application.


Try to avoid telling readers they can "just" do something. Remove the word just

Kilian · 2025-12-17T08:16:37Z

guides/mac-store.md

+
+To test your application before submitting it to the app store, you need to make sure you are actually running inside an app store sandbox, and not just running like a normal mac application.
+
+App containers are located in ```~/Library/Containers```. If there is not a folder named after your app there, then your app is not running inside a container and therefore you have messed up one of the steps in the configuration section.


"messed up" is not neutral language. Try "[...]then your app is not running inside a container. When this is the case, app-sandbox was not configured correctly, and you can find out which steps you missed by..."

Kilian · 2025-12-17T08:22:32Z

guides/mac-store.md

+
+Before packaging your application, you should also check that every file has user read permissions, and that every folder has user read and user execute permissions. Every binary should have user read and user execute permissions as well.
+
+You will also need a working help section in the menu of your app. The help section can link to a website. The electron documentation provides a basic template that you can copy and paste to make sure you have the right menu items. You just need to fix up the help section.


Try to avoid telling readers they can "just" do something. Remove the word just.

Additionally, if this is a hard requirement for the app store, explicitly state that, and provide a code example, e.g.

import electron from 'electron'; const { shell } = electon; // your help menu { role: "help", submenu: [ { label: "Documentation", click() { shell.openExternal('https://example.com'); } }, ] }

Kilian · 2025-12-17T08:23:57Z

guides/mac-store.md

+
+You will also need a working help section in the menu of your app. The help section can link to a website. The electron documentation provides a basic template that you can copy and paste to make sure you have the right menu items. You just need to fix up the help section.
+
+If your app only has one window, the app should close completely when the window is closed.


This is not what the minimal-repro example project uses. It would be good to remain consistent there.

Umm... this is required to successfully submit the app on MAS, which is what the guide is for.

Is there an Apple guideline we can reference here? I skimmed https://developer.apple.com/app-store/review/guidelines/ and might have missed it but didn't see any mention about this particular rule.

Yeah I can't find anything either but my app was rejected because of this. The way that MacOS works is that if the app is a single window utility-based application like a calculator, then it closes completely when you close. If it can be used to spawn lots of new windows (document-based), it stays open. The problem is, what about apps that have background tasks running but are single window? Mine was in this category, yet it was still rejected. Maybe the reviewer made a mistake. The assumption I took from his review was that anything that doesn't launch multiple windows should close completely.

That is also specifically what he said.

Kilian · 2025-12-17T08:24:52Z

guides/mac-store.md

+
+If your app only has one window, the app should close completely when the window is closed.
+
+Once everything is ready, you need to download Transporter from the Mac App Store and upload your ```pkg``` file.


Can you add a link to Transporter? https://apps.apple.com/us/app/transporter/id1450874784?mt=12

erickzhao

Thanks so much for this @andrewitsover! 🙇

As a note, I was wondering if you wanted to do the copy-editing adjustments from the previous review, or if you'd prefer it if a maintainer took this to the finish line?

andrewitsover added 7 commits December 15, 2025 15:06

Add Mac Store guide

8b93253

spread

b300fbd

bug

34f6e65

bugs

f4dcf49

bug

78952d1

bug

fdd40c6

bug

417ff35

Kilian reviewed Dec 17, 2025

View reviewed changes

guides/code-signing/code-signing-macos.md

packagerConfig: {

// ...

osxNotarize: {

tool: 'notarytool',

Copy link

Kilian Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this the default so should be left out

Kilian reviewed Dec 17, 2025

View reviewed changes

erickzhao reviewed Dec 18, 2025

View reviewed changes

final

342aa60


		Once you have created the certificates, you need to go to your Apple Developer Account and create provisioning profiles. If you are submiting your app to the app store, you will need a development profile and a distribution profile. If you are submiting it outside of the app store, you will need a profile for the ```Developer ID Application``` certificate.

		You need to download these after creating them and double clicking them to install them on your computer. Not all of them can be installed locally, but just double-click on them anyway.


		# App Store

		Follow the documentation on how to add Electron Forge to your project. This is fairly straight-forward, so I won't go into it.


		After the packager configuration, there is the ```maker``` configuration and some types of configuration that you can just leave as they are unless you have a use for them.

		I don't think you need any makers just for testing. Maybe add the ```zip``` maker if nothing is created. For distribution on the Mac store you need to create a ```pkg``` file.


		## Package Configuration

		Inside your ```package.json``` you might need to add a ```productName``` field. The scripts mentioned below can help you bundle and package your code.


		## Testing and Submission

		To test your application before submitting it to the app store, you need to make sure you are actually running inside an app store sandbox, and not just running like a normal mac application.


		To test your application before submitting it to the app store, you need to make sure you are actually running inside an app store sandbox, and not just running like a normal mac application.

		App containers are located in ```~/Library/Containers```. If there is not a folder named after your app there, then your app is not running inside a container and therefore you have messed up one of the steps in the configuration section.


		Before packaging your application, you should also check that every file has user read permissions, and that every folder has user read and user execute permissions. Every binary should have user read and user execute permissions as well.

		You will also need a working help section in the menu of your app. The help section can link to a website. The electron documentation provides a basic template that you can copy and paste to make sure you have the right menu items. You just need to fix up the help section.


		You will also need a working help section in the menu of your app. The help section can link to a website. The electron documentation provides a basic template that you can copy and paste to make sure you have the right menu items. You just need to fix up the help section.

		If your app only has one window, the app should close completely when the window is closed.


		If your app only has one window, the app should close completely when the window is closed.

		Once everything is ready, you need to download Transporter from the Mac App Store and upload your ```pkg``` file.

Conversation

andrewitsover commented Dec 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

erickzhao left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments