Skip to content

Writing safe integrations

Astro integrations can extend a creator-owned site. Keep new routes outside /learn; never set a lesson route to prerender: true. Keep stratolmsGuard(...) last in the integrations array so it can inspect the final routes and security policy.

Start from the generated project’s stratolms.config.mjs; preserve its video, progress, dashboard, xapi, and setup settings. Add only the origins the integration actually uses to the existing csp field:

// Add these values inside the generated csp object.
csp: {
additions: {
'script-src': ['https://plausible.io'],
'connect-src': ['https://plausible.io'],
},
allowInlineStyleAttributes: false,
},

In astro.config.mjs, import and configure your integration as needed. Keep it after the feature integrations and before the build guard:

integrations: [
mdx(),
sitemap({ filter: (url) => shouldIndex(url) }),
features(stratoConfig, { adapterName: adapter.name }),
myIntegration(),
stratolmsGuard({
onDemandRoutes: ON_DEMAND_ROUTES,
featureRoutes: enabledFeatureRoutes(stratoConfig),
}),
],

The myIntegration() line represents the integration you imported at the top of your file; retain the starter’s actual adapter, imports, and feature routes. Do not copy the fragment as a replacement for the full file or mutate security.csp from a later astro:config:setup hook, add 'unsafe-inline' or 'unsafe-eval' to script-src, use wildcard or HTTP hosts, or change locked directives. If the integration needs style attributes, review the CSP guide and make the explicit allowInlineStyleAttributes choice.

The repository’s positive compatibility fixture exercises an external script, explicit CSP hosts, and a final guard. After a local change, run pnpm stratolms check, pnpm test:integrations, and pnpm test:integration-guard from the repository. These checks do not prove a live third-party service is available.

For a presentational change, keep the source in the creator’s project. The starter includes a command that copies the built-in CourseCard source into a local override and updates its registry:

Terminal window
pnpm stratolms theme eject CourseCard

Edit src/theme/overrides/CourseCard.astro, then validate content and build the site:

Terminal window
pnpm stratolms check
pnpm build

An existing override is skipped instead of overwritten. Review the output of the eject command and keep the override in version control as ordinary source. See the theme override guide for local layout exports.

Source-copy add-ons use the same ownership model: install their files into the project, inspect the diff, and maintain the copied code with the site. Browser quizzes, printable certificates, and drip presentation do not provide secure assessment, identity, entitlement, or payment enforcement. Access policy remains in the central hasAccess gate.