Writing safe integrations
Writing safe integrations
Section titled “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.
Add an integration with an external host
Section titled “Add an integration with an external host”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.
Copy and customize a theme component
Section titled “Copy and customize a theme component”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:
pnpm stratolms theme eject CourseCardEdit src/theme/overrides/CourseCard.astro, then validate content and build the
site:
pnpm stratolms checkpnpm buildAn 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.