How shopware/developer-portal works
Project type and purpose
• This is an open-source static documentation portal (“Developer Portal”) built on top of a Vitepress template.
• It bundles a custom CLI (docs-cli.cjs) to embed and manage content from multiple Shopware sub-repositories, indexes search with Algolia, and orchestrates builds/tests/deployments via GitHub Actions.
File structure
• Top-level directories:
• .github/ – CI/CD workflows and custom GitHub Actions.
• .devcontainer/, gitpod/ – dev-environment definitions (Docker, VSCode, Gitpod).
• .vitepress/ – site configuration, theme extensions, navigation.
• src/ – markdown content, Vue components, and embedded docs mounts.
• .algolia/ – scripts and config to crawl and index site content.
• cli/ – placeholder for custom CLI (here a single docs-cli.cjs at root).
• __tests__/ – end-to-end tests (Playwright + Vitest).
• storybook/ – component previews.
• config files: package.json, tsconfig.json, vercel.json.
Extract insights from the README
• Core responsibilities:
• “Shopware Docs CLI” embeds content from external repos into the portal under src/.
• Vitepress-based front end provided by an external template package.
• Single deployment domain via GitHub Actions.
Main components
a. Developer Portal GitHub Repository
b. Shopware Docs CLI
c. External Documentation Repositories
• shopware/docs
• shopware/frontends
• shopware/meteor
• shopware/release-notes
• shopware/store-api-reference
• shopware/admin-api-reference
d. Vitepress Site Engine & Theme (external NPM package)
e. Frontend Vue Components & Markdown Content (src/ and embedded mount points)
f. Search Indexer (Algolia crawler scripts + config)
g. Storybook Component Preview Environment
h. Testing Frameworks & Suites
• E2E tests (Playwright + Vitest)
• Unit/mocks for Vitepress
i. Dev Environments
• Docker DevContainer, Gitpod
j. CI/CD Pipeline (GitHub Actions workflows)
k. Hosting/Deployment Target (Vercel or static host on developer.shopware.com)
Relationships and interactions
• Docs CLI → pulls content from External Repos → writes to src/<mount-point>/
• Vitepress Engine + Theme + src/ → generates static site build
• Algolia crawler scripts read built site files → push search index to Algolia
• Storybook reads Vue components in src/components/ → serves component library preview
• CI/CD (GitHub Actions) sequences:
1. Checkout code
2. Install dependencies
3. Run Docs CLI embed step
4. Build site with Vitepress
5. Run tests (E2E + Unit)
6. Crawl and update Algolia index
7. Deploy to hosting target
• DevContainer/Gitpod provide reproducible local dev environment for above steps.
Architectural patterns & design principles
• Modular embedding: content is not hard-coded but dynamically pulled from multiple repos.
• Separation of concerns: CLI embedding, site generation, indexing, testing, and deployment are distinct stages.
• Reusability/Extensibility: Vitepress template and CLI can be used by other teams/projects.
• Infrastructure as code: dev-containers, GitHub Actions, and scripts define environments & pipelines declaratively.
Relevant technologies, frameworks, libraries
• Node.js & npm/pnpm
• Vitepress (static site generator based on Vite + Vue)
• Vue 3 (Vue components for custom UI)
• Shopware Docs CLI (custom JavaScript script)
• Playwright + Vitest (E2E & unit tests)
• Storybook (UI component explorer)
• Algolia (search indexing)
• Docker (DevContainer, Gitpod environments)
• GitHub Actions (CI/CD)
• Vercel (or any static host for final deployment)
• Use clear labels for each of the components listed in step 4.
• “CLI → Embedded Content”
• “Repo + CLI → Build Process”
• “Build Output → Algolia”
• “Build Output → Deploy Target”
• Source & embedding
• Build & test
• Indexing & deployment
Detail
• Sub-repository integration as its own node under “External Docs.”
• GitHub Actions workflows that orchestrate each stage.
• Feedback loops (e.g., test failures trigger PR checks).