GitHub and Nuxt Content integration
The GitHub path is for websites whose content is stored as files and deployed from Git. It is strongest for Nuxt Content sites, especially when the customer already uses @nuxt/content.
For Next.js or another custom framework, use this path only when the app already has a file-backed content route that can render the files 42flows commits. Otherwise use the universal webhook.
For the broader setup hub, see the Nuxt setup guides and the Nuxt Content publishing feature page.
What gets installed
For Nuxt sites, 42flows uses the npm package:
npm install @42flowsdotcom/nuxt-content
The package provides:
| Capability | Purpose |
|---|---|
/api/42flows/content | Direct receiver endpoint for POSTing content when using direct receiver delivery. |
/api/42flows/health | Authenticated health check used by the dashboard connection test. |
| MDC components | Rich content blocks such as summaries, FAQ, sources, comparison tables, definitions, and strategy lists. |
| Route/content helpers | A Nuxt-side layer for rendering 42flows content with @nuxt/content. |
| Analytics proxy helpers | Supporting runtime routes used by the package where enabled. |
The package can run in multiple modes:
| Mode | Meaning |
|---|---|
auto | Let the module use the default 42flows behavior where possible. |
takeover | Let the 42flows route layer own the relevant content route. |
headless | Install endpoints/components without owning routes. |
dual-source | Use local content and 42flows content side by side. |
Connect flow
- The customer chooses Nuxt Content via GitHub in the dashboard.
- They install the 42flows GitHub App on the selected repository.
- The dashboard lists repositories from the installation session.
- The customer selects owner, repo, branch, and content root.
- 42flows introspects the repo.
- If the project is a Nuxt site, 42flows can add the receiver package where appropriate.
- Future content is delivered through Git commits.
The dashboard should show which repo, branch, and content folder are being used before content is published.
Repo introspection
The introspection step reads the repository before committing anything. It looks for:
package.jsonand package manager lockfiles.nuxt.config.*.content.config.ts.- Optional 42flows route configuration.
- Existing markdown/content directories.
- Route conventions that map files to public URLs.
- Default branch and repository metadata.
This is how the dashboard can explain what 42flows will change before it changes it.
Generated commits
When a flow publishes through GitHub, 42flows creates one Git commit that can include:
- The generated markdown/MDC article.
- Optional featured image assets.
- Receiver package/install changes when the setup step needs them.
- Lockfile changes when the package manager update is part of the receiver install.
42flows keeps one publication as one Git commit where possible, so the customer's deploy pipeline gets one clean change to build.
File path and public URL mapping
GitHub delivery resolves both a file path and a public URL.
Example:
| Input | Example value |
|---|---|
| Flow type | origin |
| Slug | best-ai-seo-workflow-for-dentists |
| Content root | content |
| Pattern | /blog/:slug |
| File path | content/blog/best-ai-seo-workflow-for-dentists.md |
| Public URL | https://customer.com/blog/best-ai-seo-workflow-for-dentists |
42flows should follow the route shape the site already uses. If the repo does not show a custom route, these are the default patterns:
| Flow | Pattern |
|---|---|
| Origin Flow | /blog/:slug |
| Friction Flow | /problem/:slug |
| Comparison Flow | /compare/:slug |
| Reports | /reports/:slug |
| Best/Picks | /picks/:slug |
| Cold Flow | /blog/:slug |
Direct receiver versus GitHub commit
Nuxt has two delivery styles:
| Style | How content arrives | Best fit |
|---|---|---|
| GitHub commit | 42flows commits markdown/assets into the repo. The customer's deploy pipeline builds the site. | Vercel/Netlify/GitHub-deployed Nuxt sites with file-backed content. |
| Direct receiver | 42flows sends content to /api/42flows/content with a bearer token. | Self-hosted Nuxt sites or customers that want direct delivery without Git commits. |
GitHub commit mode does not need to call /api/42flows/content for each article. The receiver package is still useful because it gives the site a known 42flows rendering and component layer.
Improving existing markdown pages
If the existing page is a markdown file in the repo, 42flows can propose file-level improvements and commit accepted changes. If a Git change needs to be undone, use the normal GitHub and deployment workflow for that repo.
Verification
After delivery, 42flows can schedule a live URL verification. The verifier fetches the public URL and checks whether the expected 42flows marker is present.
Useful outcomes:
| Result | Common cause |
|---|---|
success | Deploy finished and the page rendered with the marker. |
not_found | Deploy has not run yet, the route pattern is wrong, or content root is wrong. |
build_failure | The committed content or package install broke the customer build. |
slug_collision | The public URL belongs to a different page. |
stale_cache | The CDN or static host still serves the old build. |
Customer-facing setup checklist
For a smooth GitHub integration:
- Confirm the customer owns the repository and can install GitHub Apps.
- Confirm the repo deploys from the branch selected in the dashboard.
- Confirm the site has a public route for the intended content path.
- For Nuxt, confirm
@nuxt/contentis present or can be added. - Add
@42flowsdotcom/nuxt-contentthrough the automated install or the manual fallback. - Set the receiver/API key if direct receiver mode is used.
- Publish a test article and wait for delivery verification.
Troubleshooting
| Symptom | Check |
|---|---|
| The dashboard cannot list repos | The GitHub App installation session may have expired or the app was installed on a different account. |
| Receiver install fails | Check package manager lockfile state, Nuxt version, @nuxt/content version, and whether the branch is protected. |
| File committed but page 404s | Check content root, route pattern, slug, and deploy completion. |
| Page renders raw MDC components | The site does not have the 42flows Nuxt module/component layer active. |
| Build fails after commit | Inspect the deployment logs, then either fix the renderer/package setup or revert the commit. |
| Verification sees stale content | Purge static host/CDN cache or wait for the deployment to finish. |
When not to use GitHub delivery
Do not use GitHub delivery just because the customer code lives on GitHub. Use the webhook when:
- The app stores content in a database.
- The app uses a headless CMS.
- The app needs ISR/revalidation logic after writes.
- The app cannot render the MDC/markdown file format.
- The customer wants to validate and transform payloads before storing them.
In those cases, the customer route should receive the 42flows payload, upsert by slug, trigger cache/build work, and return the public URL.