JS Embed Guide
The JS embed is the platform-independent way to integrate Module7 into any website or CMS. It requires no server-side code — only a script tag and an HTML element, plus an optional reverse proxy.
This guide explains the underlying mechanics and requirements. It is intentionally CMS-agnostic: the same steps apply whether you are using WordPress, a custom PHP application, a static site generator, or any other environment. For concrete step-by-step instructions for a specific platform, jump directly to the relevant guide:
With the JS embed, Module7 content is fetched and rendered in the browser after the page loads. Search engine crawlers that do not execute JavaScript will see an empty <m7-view> element — the content is not indexed.
If SEO is a requirement, a server-side adapter is the right approach instead.
The JS embed relies on web server rules that route deep-linked view URLs (e.g. /listing?city=Berlin, /detail/id=abc123) to CMS pages. This works well in environments where you have full control over the web server configuration.
However, some CMS platforms manage URL routing internally and cannot delegate it to web server rules. TYPO3 is a prime example: deep-link URLs must be handled through TYPO3's own routing enhancer, which is part of the CMS adapter — plain web server rules cannot resolve those URLs correctly within TYPO3's routing lifecycle.
If you are unsure whether the JS embed is suitable for your platform, check the platform-specific guides or contact us.
Module7 is designed so that its styles do not affect the host page, and the host page's styles do not affect Module7's output. In the vast majority of cases you can embed Module7 on any website without worrying about CSS conflicts in either direction.
In rare edge cases, inherited CSS properties or global resets on the host page may still have an influence. If you observe unexpected styling, browser developer tools can help identify where the style originates.
How the embed works
When <m7-view> is placed on a page, it immediately sends a POST request to the Module7 server. The server performs a full SSR render and returns the result as JSON. The element then injects the rendered HTML into its shadow DOM and mounts the client app for interactivity.
This means SSR happens per embed, on demand — not only on direct page loads. The browser never renders Module7 content from scratch; it always receives pre-rendered HTML from the server and hydrates it.
Page loads in browser
└─ loader.js executes
└─ registers <m7-view> as a custom element
└─ connectedCallback fires
└─ POST /<view-path>
Headers: Integration-Key, Accept: application/json
Body: { language, timeZone, ... }
└─ Server renders Vue app → returns { appHtml, cssProperties, dataBlocks, assets }
└─ Element injects HTML into shadow DOM
└─ Vue hydrates → interactive
What an integration requires
A complete integration consists of these parts:
| Part | Required | Purpose |
|---|---|---|
Reverse proxy for /module7/* | Optional | Serves loader.js from the Module7 server through the host domain |
| Loader script on every page | Yes | Registers the <m7-view> custom element |
<m7-view> element on view pages | Yes | Triggers the SSR render and displays content |
| Deep-link routing | Recommended | Allows the CMS to serve Module7 view URLs as regular pages |
Part 1: Reverse proxy
A reverse proxy forwards /module7/* requests from the host domain to the Module7 server. It is optional: it lets you load the loader from your own domain (/module7/loader.js). Without a proxy, load it directly from https://mo7.vns.services/module7/loader.js (see Part 2).
Everything after the loader comes directly from the Module7 server, with or without a proxy. The loader always loads the embed bundle from https://mo7.vns.services, and the embed sends its JS chunk, stylesheet and SSR requests there as well. Make sure your Content Security Policy allows this origin.
| Path | Content | Loaded from |
|---|---|---|
/module7/loader.js | Bootstrap script — loads the hashed embed bundle | Your domain (via proxy) or the Module7 server |
/module7/entries/* | Hashed embed bundle | The Module7 server |
/module7/js/* | Hashed JS chunks | The Module7 server |
/module7/assets/* | CSS, fonts, images | The Module7 server |
Nginx example:
location ^~ /module7/ {
proxy_pass https://mo7.vns.services/module7/;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header Accept-Encoding "";
}
Apache example:
ProxyPreserveHost On
ProxyPass /module7/ https://mo7.vns.services/module7/
ProxyPassReverse /module7/ https://mo7.vns.services/module7/
If your reverse proxy or CDN caches responses, it must respect the Cache-Control headers sent by the Module7 server:
| File | Cache-Control | Why |
|---|---|---|
/module7/loader.js | public, max-age=21600 (6 hours) | Points to the current embed bundle, whose file name changes with every Module7 release |
| Embed bundles and assets (hashed file names) | public, max-age=2592000 (30 days) | A new release uses new file names, so these files never change |
Do not cache loader.js longer than 6 hours. After a Module7 release, the previous embed bundle is no longer available — a proxy that keeps serving an outdated loader.js breaks the embed on your site. With the default headers, all visitors receive a new release within 6 hours.
Part 2: Loading the loader script
The loader script must be included on every page of the host website. It registers the <m7-view> custom element. Without it, <m7-view> tags in the page markup are treated as unknown HTML and nothing renders.
Include it as a standard script tag:
<!-- With a reverse proxy -->
<script src="/module7/loader.js"></script>
<!-- Without a reverse proxy -->
<script src="https://mo7.vns.services/module7/loader.js"></script>
Place this tag in the <head> or at the end of <body>. The loader is cached by the browser for 6 hours (Cache-Control: public, max-age=21600), so there is no performance concern about including it on every page.
Automatic injection via Nginx:
If you want to avoid modifying page templates, Nginx can inject the script tag into every HTML response automatically:
sub_filter '</head>' '<script src="/module7/loader.js"></script></head>';
sub_filter_once on;
Both approaches are equivalent — use whichever fits your setup.
Part 3: Placing the <m7-view> element
Once the loader is active, place a <m7-view> element on any page where Module7 content should appear:
<m7-view
view="listing"
token="your-integration-key">
</m7-view>
The token attribute is always required. See the attribute reference for all available attributes.
Fallback for CMSes that strip custom elements
Some CMS environments sanitize HTML and remove unknown tags like <m7-view>. In these cases, use a standard <div> with data-m7-view and prefix all attributes with data-:
<div
data-m7-view
data-view="listing"
data-token="your-integration-key">
</div>
The loader automatically detects and upgrades these placeholders to proper <m7-view> elements on page load. All attributes work identically.
Part 4: Deep-link routing
By default, <m7-view> uses window.location.pathname to determine which view to render — unless the view attribute explicitly sets one. This enables URL-driven navigation: when a user shares or bookmarks a filtered URL like /listing?city=Heidelberg, the same view state is restored on load.
For this to work, the CMS must serve a page at every URL that Module7 can navigate to. Specifically:
| URL pattern | Must be handled by |
|---|---|
/listing and /listing?... | A CMS page with <m7-view token="..."> (no view attribute) |
/detail/* | A CMS page with <m7-view token="..."> (no view attribute) |
When the visitor navigates within Module7 (e.g. from listing to detail, or by changing filters), the page URL changes. If the user then refreshes the page, the CMS must serve its page at that URL — otherwise a 404 is returned.
If you use the view attribute to hard-code the view, Module7 ignores the URL path. The listing then needs no routing of its own: it keeps filters, search, sort and page in m7- parameters of your page's URL — see URL state.
Detail links still point to /detail/id=... on your domain. If the view links to detail pages (listing, grid, slide), you still need a CMS page at /detail/*.
The X-Original-URL header
The JS embed sends its SSR requests directly from the browser to the Module7 server — they never pass through your reverse proxy. The X-Original-URL header is therefore not needed for the JS embed. It is only relevant for server-side adapters, see Building a CMS Adapter.
Verifying the integration
Once everything is in place, open your browser's developer tools and check:
- Network tab — you should see a
POSTrequest to/listing(or whichever view) returning a JSON response withappHtml. - Elements tab —
<m7-view>should have a shadow root containing the rendered HTML. - Console — any configuration errors (missing token, invalid filter, unknown view) are shown as styled error messages inside the element and as
logger.errorcalls in the console.