How rtcamp/snapwp works
Main Components
• Core Functionality:
• @snapwp/core (located in packages/core): Contains core utilities, configuration management, logging, error handling, and other fundamental functions.
• Next.js Integration:
• @snapwp/next (located in packages/next): Provides the integration layer for Next.js, offering middleware, React components (like custom Link, Image, Error handling, and template renderers), and custom configuration for SnapWP.
• Block Management:
• @snapwp/blocks (located in packages/blocks): Manages the rendering of WordPress blocks. It includes block definitions, default and custom block components for handling various core blocks (e.g., audio, button, gallery, etc.) plus test suites.
• Query/GraphQL Handling:
• @snapwp/query (located in packages/query): Centralizes WPGraphQL query handling, providing fragments, queries, and query engine functionality for fetching data from WordPress.
• Developer Tooling:
• CLI: @snapwp/cli for bootstrapping applications (found in packages/cli).
• Codegen & Linting Configurations: Packages such as @snapwp/codegen-config, @snapwp/eslint-config, and @snapwp/prettier-config.
• External WordPress Plugin:
• The SnapWP Helper plugin (referenced in the README) that enhances WordPress and WPGraphQL on the CMS side.
• Examples & Documentation:
• Provided examples (like the Next.js starter app in examples/nextjs) serve as practical implementations to illustrate integration.
• Infrastructure & Configuration:
• Various configuration files (in config, .env.example, GitHub workflows, etc.) indicate automated builds, test setups, and deployment pipelines.
Their Relationships and Interactions
• The “Core” package provides foundational services that are consumed by the other packages.
• The Next.js integration layer uses both the Core and Blocks packages to assemble the frontend application.
• The Blocks package renders WordPress block data by interfacing with the Query package, which in turn communicates with WPGraphQL.
• The CLI & developer tooling packages (CLI, codegen, eslint, prettier) support application setup, manage configurations, and improve developer experience.
• There is an external dependency on the SnapWP Helper plugin installed on the WordPress server, which provides necessary hooks, additional functionality, and validates the WPGraphQL endpoints.
• Build and deployment workflows are handled via GitHub Actions (in .github/workflows) and local scripts (e.g., bin/publish-local.sh).
Important Patterns and Design Principles
• Composability: Separate packages allow developers to choose individual functionalities (e.g., query handling, block rendering, or Next.js configuration) and override parts as needed.
• Modularity: Each package focuses on a specific domain (core utilities, next integration, UI blocks, data querying), making the system easier to understand and maintain.
• Extensibility: The design facilitates granular overrides to extend or customize behaviors, emphasizing progressive enhancement rather than a monolithic architecture.
• Separation of Concerns: Distinct areas for frontend integration (Next.js), backend data management (GraphQL queries via @snapwp/query), and core utilities (@snapwp/core).
◦ Clear labels for each component (e.g., “Core”, “Next.js Integration”, “Block Renderer”, “GraphQL Query Engine”, “CLI/Tooling”).
▪ From WordPress (SnapWP Helper) to GraphQL Query Engine.
▪ From Core utilities to the various packages.
▪ From Next.js integration and Blocks rendering components pulling data through GraphQL.
◦ Annotations noting important configuration or deployment flows (GitHub workflows, build scripts, etc.).