From source files to a sellable Matrix experience.
This guide explains how to install, configure, customize, test, and publish the Hedomi Matrix of Destiny calculators on Shopify—without editing a theme’s source code.
What you are installing
A Shopify Theme App Extension containing four independent app blocks. Combine them to build free calculators, premium interpretations, and downloadable reports.
0.6.1
- Flexible report sections
- Energy texts 1–22
- Point selection such as n5
- Login or purchase access
- Browser-generated PDF
Install the extension in a Shopify app project
You only replace or add the extension folder. Keep the root files created by Shopify.
Requirements
On your computer
- Node.js 22.12 or newer
- Git
- Shopify CLI
- A code editor such as VS Code
In Shopify
- A Shopify store for testing or installation
- Access to the Shopify Dev Dashboard
- Permission to install and manage apps
- An Online Store 2.0 compatible theme
Install Shopify CLI
npm install -g @shopify/cli@latest
shopify versionIf the CLI reports an unsupported Node engine, update Node before continuing.
Log in and create a Shopify app project
shopify app initFollow the prompts and create or select an app. The exact templates offered by Shopify may change. The Hedomi files belong inside the generated extensions directory.
Copy the Hedomi extension
From the purchased package, copy:
extensions/hedomi-matrix-calculators
Into your Shopify project:
YOUR-APP/extensions/hedomi-matrix-calculators
Install dependencies and validate
cd /d C:\path\to\your\shopify-app
npm install
shopify app buildOn macOS or Linux, use a normal cd /path/to/project command.
Expected structure
your-shopify-app/
├─ extensions/
│ ├─ app-home/
│ ├─ app-tools/
│ └─ hedomi-matrix-calculators/
│ ├─ assets/
│ ├─ blocks/
│ ├─ locales/
│ ├─ snippets/
│ ├─ package.json
│ └─ shopify.extension.toml
├─ package.json
└─ shopify.app.tomlTest first. Publish when the result is ready.
Start a development preview
shopify app devLeave the terminal running while you test. Open the dev preview, then open the theme editor.
Add a block to the storefront
- Open Online Store → Themes.
- Click Customize on the theme used for testing.
- Open the page or template where the calculator should appear.
- Click Add section or Add block.
- Open the Apps tab.
- Add one of the Hedomi blocks and save.
Publish the app version
shopify app build
shopify app deployDeploying creates a version of the app components. Installing the app and publishing a theme are separate Shopify actions.
The package contains four building blocks
Single Matrix
The individual calculator, matrix chart, main energies, chakra table, purposes, product button, and PDF settings.
Single explanation
A freely named report section connected to one matrix point and 22 possible energy explanations.
Couple Matrix
Two personal charts, one combined chart, couple purposes, product button, and PDF settings.
Couple explanation
A flexible section that can read a point from the first person, second person, or combined couple matrix.
Configure the individual calculator
Add the Single Matrix block, then edit its content, visuals, PDF, and product settings in the theme editor.
- Calculator key
- Default: single-main. Use this exact key in every connected Single explanation block.
- Name & birth date
- The name field can be shown or hidden. The birth date is required for calculation.
- Main values
- True essence, projected image, divine talent, financial energy, ideal partner, and personal purpose.
- Chakra table
- Can be shown or hidden. Includes Energy, Physical, Emotions, and Total values.
- Purposes
- Can display personal, social, and spiritual purpose calculations.
- Chart image
- Use the included image or upload a compatible square background.
- Appearance
- Primary, text, background, cards, borders, chakra colors, and radius.
- Product
- Select a Shopify product and optionally show an Add to cart button.
Built-in point references
| Displayed value | Matrix point | Dynamic token |
|---|---|---|
| True essence / core | n30 | [[core]] |
| Projected image | n1 | [[image]] |
| Divine talent | n3 | [[talent]] |
| Financial energy | n27 | [[money]] |
| Ideal partner | n29 | [[partner]] |
| Personal purpose | n58 | [[personal_purpose]] |
| Social purpose | n61 | [[social_purpose]] |
| Spiritual purpose | n63 | [[spiritual_purpose]] |
Configure the compatibility calculator
The Couple Matrix block calculates two individual matrices and one combined relationship matrix.
- Calculator key
- Default: couple-main. All connected Couple explanation blocks must use the same key.
- Names & dates
- Both names and birth dates are entered in the calculator form.
- Personal charts
- Choose whether the first and second person charts are displayed.
- Combined chart
- The couple matrix is always the main compatibility result.
- Purposes
- The block displays personal and social purpose values for the couple matrix.
- Chart image
- One selected image is used for the individual and combined chart backgrounds.
Choose which chart controls an explanation
Every Couple explanation block has a Read point from setting:
First person matrix
Reads the selected point from the first birth date.
Second person matrix
Reads the selected point from the second birth date.
Couple matrix
Reads the selected point from the combined relationship matrix.
Create any report section you need
There are no predefined interpretation topics. You decide the section title, matrix point, energy texts, access rule, and PDF inclusion.
Add an explanation block
In the theme editor, select Add section → Apps → Single explanation or Couple explanation.
Connect it to the calculator
Copy the calculator’s key exactly. Keys are case-sensitive and should not contain accidental spaces.
Name the section
Examples: “My essence”, “Financial path”, “Family patterns”, “Relationship dynamics”, or any title used in your method.
Select the matrix point
Choose the point that controls the section, such as n5, n27, or n63.
Write explanations for energies 1–22
Only the text corresponding to the calculated energy is shown to the visitor. Rich text supports paragraphs, emphasis, links, and lists provided by Shopify’s editor.
Duplicate and reorder
Add as many independent explanation blocks as your report needs. Drag them into the desired storefront and PDF order.
Section planning assistant
Before and after calculation
- Before calculation, the block displays its configurable waiting text.
- After calculation, it reads the selected point and finds the matching Energy 1–22 field.
- If that energy field is empty, it displays the configurable fallback text.
- The energy-number badge can be shown or hidden.
Choose who can read each explanation
| Access mode | Who sees the content | Typical use |
|---|---|---|
| Everyone | All visitors | Free samples or a complete free calculator. |
| Logged-in customers | Any customer logged into the store | Member-only or lead-generation content. |
| Purchased product | A logged-in customer whose eligible order contains the selected product | Paid interpretations and PDF access. |
How purchase verification works
The extension checks the logged-in customer’s orders in Shopify Liquid. It ignores cancelled orders and grants access when an order containing the selected product is marked paid or partially refunded.
Locked state
You can customize the locked heading, message, login button label, purchase button label, and missing-product message.
Sell a personalized report through the cart
The calculator can add a selected Shopify product to the cart together with calculated data as line-item properties.
Create the report product
Create a normal Shopify product with the price, title, description, and availability you want.
Select it in the calculator
Open the calculator block settings and choose the product under Shopify product.
Enable the cart button
Activate Show Add to cart button and customize the label and success message.
Protect the report sections
In each explanation block, choose Purchased product and select the same report product.
Data saved with the cart item
Single report
Name, birth date, matrix core, personal purpose, social purpose, spiritual purpose, and calculator type.
Couple report
Both names, both birth dates, couple core, and calculator type.
Generate a real downloadable PDF in the browser
The extension creates the PDF directly on the visitor’s device. It does not open the browser’s print dialog.
What the PDF can contain
- Cover page with optional full-page image, title, subtitle, logo, names, and birth dates
- Main energies and Matrix chart
- Single chakra table and purpose sections
- Couple charts and couple-purpose values
- Connected explanation blocks marked Include this section in the PDF
- Optional final-page image
PDF configuration
- Enable PDF
- Shows or hides the download feature.
- Require premium access
- Uses the calculator block’s premium-access rule to decide whether the button is rendered.
- PDF title & subtitle
- Displayed on the cover and can include supported dynamic tokens.
- Filename
- Example: matrix-of-destiny-[[name]].
- Cover image
- Optional full-page visual behind the cover layout.
- Logo
- Optional brand logo on the cover.
- Content background
- Optional background for report pages. Use a light, low-contrast image.
- Final image
- Optional standalone last page.
Use custom visuals without moving the calculated points
Chart background image
The uploaded chart image must use the same geometry as the default image. The number nodes are positioned independently above the background, so a visually different diagram can cause misalignment.
Recommended
- Square image
- Same line intersections
- Same center and outer points
- High resolution
- Uploaded through Shopify
Avoid
- Different chart proportions
- Cropped or padded diagrams
- Remote images with access restrictions
- Heavy text behind point numbers
- Dark PDF page backgrounds
PDF image troubleshooting
Use Shopify-hosted files selected through the image picker. Browser security can prevent the PDF engine from reading some externally hosted images.
Insert calculated values into titles and explanations
Use square-bracket tokens such as [[name]]. Curly-bracket Liquid-like tokens are not recommended in Shopify schema settings.
Single tokens
| Token | Value |
|---|---|
| [[name]] | Customer name or “Client” fallback |
| [[birthdate]] | Entered birth date |
| [[core]] | n30 |
| [[image]] | n1 |
| [[talent]] | n3 |
| [[money]] | n27 |
| [[partner]] | n29 |
| [[personal_purpose]] | n58 |
| [[social_purpose]] | n61 |
| [[spiritual_purpose]] | n63 |
| [[energy]] | Energy controlling the current explanation block |
| [[point]] | Resolved matrix point |
Couple tokens
| Token | Value |
|---|---|
| [[first_name]] | First person’s name |
| [[second_name]] | Second person’s name |
| [[first_birthdate]] | First birth date |
| [[second_birthdate]] | Second birth date |
| [[first_core]] | First person core |
| [[second_core]] | Second person core |
| [[couple_core]] | Combined couple core |
| [[personal_purpose]] | Couple personal purpose |
| [[social_purpose]] | Couple social purpose |
| [[energy]] | Energy controlling the current section |
| [[point]] | Resolved point, including the selected chart source |
Example
[[name]], the energy in this section is [[energy]].
Your main matrix core is [[core]].Translate the customer-facing experience
Most visible headings, field labels, button labels, status messages, locked messages, PDF titles, and explanation texts are editable directly in the theme editor.
Bundled locale files
- locales/en.default.json
- locales/pt-BR.json
These files contain system labels such as the Single chakra-table headings. Developers can edit them before deployment or add another supported locale file.
Replace only the extension folder
Stop the running preview
Press Ctrl + C in the terminal.
Back up your project
Keep a copy before replacing source files, especially if you manually edited CSS or locale files.
Replace the old folder
Delete and replace extensions/hedomi-matrix-calculators. Do not replace your root shopify.app.toml.
Clean and validate
rmdir /s /q .shopify
shopify app build
shopify app devFor macOS/Linux, remove the cache with rm -rf .shopify.
Deploy after testing
shopify app deployCommon problems and direct fixes
Shopify CLI fails before starting
Run node -v. Shopify CLI currently requires Node.js 22.12 or newer. Activate a compatible version, reinstall the CLI for that Node version, and run the command again.
Windows reports “operation not permitted, chmod”
Stop all Shopify processes. Move the project away from Desktop, OneDrive, or another synchronized/protected folder—for example, C:\shopify-dev\your-app. Delete .shopify and retry. An administrator terminal may also help.
The Hedomi blocks do not appear in the theme editor
Confirm that shopify app dev is running or that the latest extension version was deployed. Open a template that accepts app blocks, use Add section/block → Apps, and refresh the theme editor.
An explanation keeps showing “Calculate the matrix…”
Check that the calculator and explanation use the same Calculator key, that both are Single or both are Couple, and that the matrix calculation completed successfully.
The explanation displays the wrong energy
Check the selected Matrix point. For Couple explanations, also verify whether the source is First person, Second person, or Couple matrix.
The fallback says no explanation was added
The selected point calculated an energy whose corresponding Energy 1–22 rich-text field is empty. Add content to that exact energy field.
A customer purchased but still sees the locked message
The customer must be logged in. Verify that the same Shopify product is selected in the protected block, the order is not cancelled, and its financial status is paid or partially refunded. Then refresh the storefront.
The PDF does not include an explanation section
Enable “Include this section in the PDF,” use the matching Calculator key, calculate the matrix first, and make sure the customer has access to the section. Locked or hidden sections are not added.
The PDF cannot use an uploaded image
Choose images through Shopify’s image picker instead of entering a remote URL. External image permissions can block browser-based PDF generation.
The numbers no longer align with the chart
Restore the default chart image or upload a square image with exactly the same diagram geometry. A differently cropped or redesigned diagram changes the visual position of the lines, not the number-node coordinates.
Understand what version 0.6.1 does—and does not do
Included
- Calculations performed in the browser
- Single and Couple charts
- Flexible sections controlled by matrix points
- 22 explanations per section
- Login and purchase-based access
- Shopify product cart integration
- Downloadable browser-generated PDF
Not included
- A server-side report database
- Automatic PDF email delivery
- A saved-report customer dashboard
- One unique report credit per purchase
- Automatic interpretation translation
- Automatic App Store publication
Launch checklist
Check each item. Your progress appears at the top of this guide.