Update and Publish a Module

Overview

We have several modules in the Mendix Marketplace that are commonly used. Instructions to update the module are in ReadMeExportModule under the _Docs directory of the module. The instructions are replicated here.

1. Get module project. All are named with "- MARKETPLACE".
2. Follow instructions in ReadMeExportModule under the _Docs directory to prepare for module export.
3. Export module package.
4. Import module package to project and test.
5. Upload and publish to Mendix Marketplace.
6. Update the BYU Starter App if it uses the module.

1. Get module project.

All module projects are named with "- MARKETPLACE". It's best to work in a branch from main and merge it back to main after code review and approval.

2. Follow instructions in ReadMeExportModule under the _Docs directory.

Open ReadMeExportModule under the _Docs directory.

1. Update the version of the module. There is a folder under the _Docs folder named with the version number. Right-click and rename it to the next version number.

We use semantic versioning, major.minor.patch. If it's a minor change, increment the patch version number (the last one). If it's a significant change, increment the minor version number (the middle one). If it's a major change or it breaks something, update the major version number (the first one).

2. Update ReadMe if needed. It's under the _Docs folder.

3. Check ReadMeExportModule for any dependencies to be included when exporting. Most of our modules have no dependencies. If you added dependencies to the module, update ReadMeExportModule. Dependencies can be a Java class, Javascript file, image, or custom HTML or CSS used in the module. Update ReadMeExportModule if you have added dependencies.

3. Export module package.

Open ReadMeExportModule under the _Docs directory. Find the step that says "Deselect all dependencies, except" or the Dependencies section and note which dependencies to include or exclude when you export.

Right-click on the module in App Explorer (left sidebar) and select Export module package...

A warning will display that recommends removing all usages of other modules before export. Ignore it and select Continue exporting.

A list of all dependencies to include will then display. Deselect all dependencies and select only the ones listed in the ReadMeExportModule. Most of our modules have no dependencies. If you added dependencies to the module, update the documentation in ReadMeExportModule. Dependencies can be a Java class, Javascript file, image, or custom HTML or CSS used in the module.

Save the module .mpk file in a place where you can retrieve it and import it into a new project.

4. Test the module by importing to a test project.

Use an existing Mendix project or create a new local project from the BYU Starter App to import the module and test it.

Right-click the top-level App in App Explorer, choose Import module package... and find the .mpk file you exported.

If the module already exists in the project, the radio button option will be "Replace existing module". Select Import.

4. Upload and publish to Mendix Marketplace.

You must be part of the Low-Code Team group to be able to edit and publish to the Mendix Marketplace. Ask a Mendix developer to add you to the group if you don't have access.

Go to Mendix Marketplace and sign in.

Go to Company > Components in the navigation menu on the left.

Find the component (module) that you will update, click the three-dot (...) option, and select Add New Release.

If you can't select Add New Release, someone else may be publishing a release. Have that person finish publishing so you can add a release.

A dialog will display with "Before You Get Started" reminding you that you will need a source file (the .mpk file you exported) or GitHub link (you won't need one), a thumbnail image (already exists since you're editing, not creating a new module), and screenshots. If you made significant changes, add new screenshots if it will help the person using the module.

Click on Upload MPK File to upload the .mpk file you exported. Once it shows the file was uploaded, click on Upload Source File to complete it.

Manually modify the Release Version to match the one you set in the project. Do not skip this step.

Add a release note explaining what changed. Do not skip this step.

We usually don't modify the following options but do so if it makes sense. Select Next to continue until you get to the page with the Publish Component button.

When you're done, select Publish Component to finish publishing.

If at any point you need to stop before publishing, select Save and Exit. This will keep a draft that you can return to. Even if you don't save your progress, a draft was created when you selected Add New Release. No one else can publish a new release until you finish publishing the draft or discard it. Please don't leave a draft for long. To see your drafts, go to Personal > Drafts. You can select a draft and continue to edit and publish or delete it.

5. Update the BYU Starter App if it uses the module.

Follow a similar procedure to update the BYU Starter App, though this is an application package, not a module, and there are slight differences. Other than updating Marketplace modules, most of the changes you make will be under the Main module at the bottom.

Make a branch of the BYU Starter App - MARKETPLACE project.

Import the MPK file.

Test that everything works.

Update the version number under Main > _Docs.

Update ReadMe and ReadMeExportAppPackage if needed under Main > _Docs.

Follow instructions in ReadMeExportAppPackage to test and export.

Test Before Publishing

1. Export an app package by right-clicking on App BYU Starter App 10 - MARKETPLACE in App Explorer (left side) and selecting Export app package... Don't export data. Select No data option when exporting. Save it where you can retrieve it.

NOTE: don't export a module. This is an app package not a module.

Check the size of the .mpk file. It should be less than 100 MB or you won't be able to upload it to Mendix Marketplace. The latest version is under 60 MB. If it is too large, check the userlib and vendorlib directory under the root project directory in Windows File Explorer to see if there are duplicate .jar files that differ only by version number. These can quickly increase the package size. Remove older versions, but test that the application still runs before finalizing and publishing.

2. Start another instance of Studio Pro and select + Create New App.

3. Don't use a template. Go to File > Import App Package... and select the .mpk file you exported in Step 1.

4. Select Locally on disk, give it an App name like "TestApp," and select OK to generate an app from the .mpk file template.

Run the app to make sure it works.

Once it's ready to publish, follow the Upload and publish to Mendix Marketplace step above.