{"id":22861570,"url":"https://github.com/sethburtonhall/contentful-nextjs-headless","last_synced_at":"2026-02-09T18:31:55.008Z","repository":{"id":267852644,"uuid":"902486735","full_name":"sethburtonhall/contentful-nextjs-headless","owner":"sethburtonhall","description":"Contentful Next.js Headless Starter","archived":false,"fork":false,"pushed_at":"2025-01-07T18:13:23.000Z","size":287,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-02T16:12:06.694Z","etag":null,"topics":["contentful","headless","jotai","mux","nextjs","shadcn","tailwindcss","tanstack-form","tanstack-query","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sethburtonhall.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-12T16:56:12.000Z","updated_at":"2025-01-07T18:13:27.000Z","dependencies_parsed_at":"2024-12-12T21:30:03.753Z","dependency_job_id":null,"html_url":"https://github.com/sethburtonhall/contentful-nextjs-headless","commit_stats":null,"previous_names":["sethburtonhall/contentful-nextjs-headless"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethburtonhall%2Fcontentful-nextjs-headless","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethburtonhall%2Fcontentful-nextjs-headless/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethburtonhall%2Fcontentful-nextjs-headless/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethburtonhall%2Fcontentful-nextjs-headless/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sethburtonhall","download_url":"https://codeload.github.com/sethburtonhall/contentful-nextjs-headless/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252854268,"owners_count":21814656,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["contentful","headless","jotai","mux","nextjs","shadcn","tailwindcss","tanstack-form","tanstack-query","typescript"],"created_at":"2024-12-13T10:09:35.640Z","updated_at":"2026-02-09T18:31:49.946Z","avatar_url":"https://github.com/sethburtonhall.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Contentful Mux Next.js Starter\n\nThis is a starter template for building a blog with Next.js, Contentful, and Mux. It includes a Docker-based development workflow for a consistent development experience across teams.\n\n## Prerequisites\n\n- Docker Desktop installed and running\n- Git\n\nNo other local dependencies are required! Everything runs inside Docker containers.\n\n## Development Workflow\n\n### Initial Setup\n\n1. Clone the repository:\n\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd contentful-mux-nextjs-starter\n   ```\n\n2. Copy the environment file:\n\n   ```bash\n   cp .env.example .env.development\n   ```\n\n3. Update `.env.development` with your credentials:\n   - `CONTENTFUL_SPACE_ID`\n   - `CONTENTFUL_ACCESS_TOKEN`\n   - `CONTENTFUL_PREVIEW_ACCESS_TOKEN`\n   - `MUX_TOKEN_ID`\n   - `MUX_TOKEN_SECRET`\n\n### Docker Development\n\nOur Docker setup provides a consistent development environment with:\n\n- 🔥 Hot-reloading for instant feedback\n- 📦 Cached node_modules for faster builds\n- 🛠️ Built-in debugging support\n- 🔍 Health checks for reliability\n- 👤 Secure non-root user setup\n\n#### Docker Commands\n\n```bash\n# Start development server\nnpm run docker:start\n\n# Build the application\nnpm run docker:build\n\n# Run linting and type checking\nnpm run docker:check\n\n# Stop the development server\nnpm run docker:down\n\n# Clean up containers and volumes\nnpm run docker:clean\n\n# Remove all Matic Docker resources\nnpm run docker:purge\n```\n\n#### Development Features\n\n- **Hot Reloading**: Changes to your code will automatically trigger rebuilds\n- **Container Management**: \n  - The container is named `Matic-Docker-App` for easy identification\n  - Volumes are prefixed with `matic-docker-` for organization\n- **Automatic Cleanup**: \n  - Pressing Ctrl+C during development automatically cleans up resources\n  - `docker:check` automatically manages container lifecycle\n- **Development Tools**:\n  - Access container shell: `./scripts/dev shell`\n  - View logs: `./scripts/dev logs`\n  - Check status: `./scripts/dev status`\n\n#### Best Practices\n\n1. **Development Workflow**\n   - Use `npm run docker:start` for daily development\n   - Run `npm run docker:check` before committing changes\n   - Keep the logs visible for debugging\n\n2. **Resource Management**\n   - Use `npm run docker:clean` to clean up after development\n   - Use `npm run docker:purge` when switching branches or for deep cleaning\n\n3. **Troubleshooting**\n   - Check container status with `./scripts/dev status`\n   - View logs with `./scripts/dev logs`\n   - If in doubt, run `npm run docker:purge` and start fresh\n\n### Non-Docker Development\n\nIf you prefer to develop without Docker, you'll need:\n- Node.js (version specified in package.json)\n- npm (version specified in package.json)\n\nThen you can use these commands:\n```bash\n# Install dependencies\nnpm install\n\n# Start development server\nnpm run dev\n\n# Build the application\nnpm run build\n\n# Run linting and type checking\nnpm run check\n```\n\n## Feature Development Workflow\n\nOur feature development workflow is designed to maintain high code quality and consistency across the team. Follow these guidelines for all feature development:\n\n### 1. Branch Management\n\n  \u003c!-- \u003ctype\u003e/\u003cticket-number\u003e-\u003cbrief-description\u003e --\u003e\n- **Branch Naming Convention**: \n  ```\n  \u003ctype\u003e/\u003cticket-number\u003e-\u003cbrief-description\u003e\n  ```\n  - Types: `feature`, `bugfix`, `hotfix`, `refactor`, `docs`\n  - Example: `feature/MATIC-123-add-video-player`\n\n- **Branch Lifecycle**:\n  1. Create from latest `main`\n  2. Regular commits during development\n  3. Rebase with `main` before PR\n  4. Delete after merge\n\n### 2. Development Process\n\n1. **Planning**:\n   - Review ticket requirements\n   - Break down into tasks\n   - Identify affected components\n   - Plan test coverage\n\n2. **Local Development**:\n   ```bash\n   # Start fresh with a new branch\n   git checkout main\n   git pull\n   git checkout -b feature/MATIC-XXX-description\n   \n   # Start development environment\n   npm run docker:start\n   ```\n\n3. **Development Loop**:\n   - Write code with hot-reloading\n   - Run checks frequently:\n     ```bash\n     npm run docker:check\n     ```\n   - Commit logical chunks of work\n   - Update tests and documentation\n\n### 3. Code Quality Standards\n\n- **Commit Messages**:\n  ```\n  \u003ctype\u003e: \u003cdescription\u003e\n  \n  [optional body]\n  [optional ticket reference]\n  ```\n  - Types: `feat`, `fix`, `refactor`, `docs`, `style`, `test`, `chore`\n  - Example: `feat: add video player component`\n\n- **Pre-commit Checks**:\n  - Linting (ESLint)\n  - Type checking (TypeScript)\n  - Code formatting (Prettier)\n  - Unit tests (if applicable)\n\n- **Code Style**:\n  - Follow ESLint configuration\n  - Use TypeScript strictly\n  - Document complex logic\n  - Keep components focused\n  - Follow project structure\n\n### 4. Pull Request Process\n\n1. **Preparation**:\n   ```bash\n   # Ensure all changes are committed\n   git status\n   \n   # Rebase with main\n   git checkout main\n   git pull\n   git checkout your-branch\n   git rebase main\n   \n   # Verify everything works\n   npm run docker:purge  # Clean slate\n   npm run docker:start  # Verify app works\n   npm run docker:check  # Run all checks\n   ```\n\n2. **PR Creation**:\n   - Use PR template\n   - Link related tickets\n   - Add screenshots/videos if UI changes\n   - Tag relevant reviewers\n\n3. **PR Description**:\n   - Summarize changes\n   - List testing steps\n   - Note any breaking changes\n   - Include deployment considerations\n\n4. **Review Process**:\n   - Address review comments\n   - Keep PR updated with main\n   - Get required approvals\n   - Ensure all checks pass\n\n### 5. Testing Requirements\n\n- **Unit Tests**: Required for utilities and hooks\n- **Integration Tests**: Required for complex features\n- **UI Tests**: Required for critical user flows\n- **Manual Testing**:\n  - Test in development environment\n  - Cross-browser testing if needed\n  - Mobile responsiveness if applicable\n\n### 6. Documentation\n\n- Update README if needed\n- Add inline documentation\n- Update API documentation\n- Document breaking changes\n- Add usage examples\n\n### 7. Deployment\n\n1. **Staging**:\n   - Automatic deployment on PR\n   - Verify features in staging\n   - Run smoke tests\n\n2. **Production**:\n   - Merge to main\n   - Monitor deployment\n   - Verify in production\n   - Be ready to rollback\n\n### 8. Troubleshooting\n\nIf you encounter issues:\n\n1. **Docker Issues**:\n   ```bash\n   # Clean slate approach\n   npm run docker:purge\n   docker system prune -af  # Be careful with this!\n   npm run docker:start\n   ```\n\n2. **Development Issues**:\n   - Check container logs: `./scripts/dev logs`\n   - Verify environment variables\n   - Clear node_modules: `npm run docker:clean`\n\n3. **Build Issues**:\n   - Verify dependencies\n   - Check TypeScript errors\n   - Review build logs\n\n### 9. Best Practices\n\n- Keep PRs focused and small\n- Write descriptive commit messages\n- Update tests with code changes\n- Document complex logic\n- Follow the single responsibility principle\n- Use feature flags for big changes\n- Keep dependencies updated\n- Monitor performance impacts\n\n## Pull Request Template\n\nWhen creating a pull request, copy and fill out the following template:\n\n```markdown\n# Description\n\nPlease include a summary of the changes and the related issue. Please also include relevant motivation and context.\n\nFixes # (issue)\n\n## Type of change\n\nPlease delete options that are not relevant.\n\n- [ ] Bug fix (non-breaking change which fixes an issue)\n- [ ] New feature (non-breaking change which adds functionality)\n- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)\n- [ ] This change requires a documentation update\n\n## How Has This Been Tested?\n\nPlease describe the tests that you ran to verify your changes. Provide instructions so we can reproduce.\n\n- [ ] Test A\n- [ ] Test B\n\n## Checklist:\n\n- [ ] My code follows the style guidelines of this project\n- [ ] I have performed a self-review of my code\n- [ ] I have commented my code, particularly in hard-to-understand areas\n- [ ] I have made corresponding changes to the documentation\n- [ ] My changes generate no new warnings\n- [ ] I have added tests that prove my fix is effective or that my feature works\n- [ ] New and existing unit tests pass locally with my changes\n- [ ] Any dependent changes have been merged and published in downstream modules\n\n## Screenshots (if applicable):\n\n## Additional context:\n\nAdd any other context about the pull request here.\n\n## Deployment Notes:\n\nDescribe any deployment steps, configuration changes, or other considerations.\n```\n\n## Project Structure\n\n```\ncontentful-mux-nextjs-starter/\n├── docker/                    # Docker-related files\n│   ├── Dockerfile           # Development Dockerfile\n│   └── docker-compose.yml   # Development compose configuration\n├── src/                      # Application source code\n│   ├── app/                 # Next.js app router files\n│   ├── components/          # Reusable React components\n│   ├── hooks/               # Custom React hooks\n│   ├── lib/                 # Utility functions and libraries\n│   └── styles/              # CSS and styling files\n├── .env.development         # Development environment variables\n├── .env.example            # Template for environment variables\n├── package.json            # Node.js dependencies and scripts\n└── README.md               # Project documentation\n```\n\n## Project Standards\n\nhttps://github.com/alan2207/bulletproof-react/blob/master/docs/project-standards.md\n\n- ESlint\n  - file naming conventions\n- Prettier\n- TypeScript\n- Husky\n  - pre-commit hooks\n- absolute imports\n  - tsconfig.json\n\n## Project Structure\n\nhttps://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md\n\n## Components and Styling\n\nhttps://github.com/alan2207/bulletproof-react/blob/master/docs/components-and-styling.md\n\n- shadcn/ui for UI components\n  - Radix Primitives\n  - TailwindCSS\n  - components.json for configuration\n\n## API Layer\n\nhttps://github.com/alan2207/bulletproof-react/blob/master/docs/api-layer.md\n\n- **Contentful** GraphQL Content Delivery API\n  - fetchGraphQL function\n  - custom getters\n  - custom server side functions\n- **Tanstack Query**\n  - uses api fucntions custom client hooks\n- **Mux** for video streaming\n  - the plabackId from the Contentful API\n  - the muxData from the Mux API\n\n## Data Fetching\n\n- **React Query** for data fetching\n- **React Query DevTools** for debugging\n\n## State Management\n\nhttps://github.com/alan2207/bulletproof-react/blob/master/docs/state-management.md\n\n- **useState** for component state\n- **Jotai** for application state management\n- **Jotai DevTools** for debugging\n\n## Form Validation and State Management\n\n- **@tanstack/react-form** for form state management\n- **@tanstack/zod-form-adapter** for form validation\n\n## Error Handling\n\nhttps://github.com/alan2207/bulletproof-react/blob/master/docs/error-handling.md\n\n- **API Errors** for server-side errors\n- **React Error Boundary** for component-level error handling\n- **ErrorPage** for custom error pages\n\n## Animation Decision Framework\n\nWhen implementing animations in your components, ask these questions to determine the best approach:\n\n1. **Is it a simple state transition?**\n   - If yes → Use Tailwind animations\n   - Examples: hover states, fade-ins, simple transitions\n\n2. **Does it need user interaction?**\n   - Basic interaction → Use Tailwind animations\n   - Complex interaction (gestures, drag) → Use Framer Motion\n   - Examples: \n     - Tailwind: hover effects, click feedback\n     - Framer: drag and drop, pinch to zoom\n\n3. **Does it need to respond to gestures?**\n   - If yes → Use Framer Motion\n   - Examples: swipe actions, pull to refresh\n\n4. **Is it purely decorative?**\n   - If yes → Use Tailwind animations\n   - Examples: loading states, entrance animations\n\n5. **Does it need to coordinate with other elements?**\n   - If yes → Use Framer Motion\n   - Examples: synchronized animations, staggered lists\n\nSee the animation examples in `src/app/template/page.tsx` for implementation details.\n\n## Testing\n\nTBD\nhttps://github.com/alan2207/bulletproof-react/blob/master/docs/testing.md\n\n## Security (Authentication and Authorization)\n\nhttps://github.com/alan2207/bulletproof-react/blob/master/docs/security.md\nTBD\n\n## Deployment\n\nhttps://github.com/alan2207/bulletproof-react/blob/master/docs/deployment.md\n\n## Contributing\n\n1. Create a feature branch\n2. Make your changes\n3. Submit a pull request\n\n## License\n\n[MIT License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsethburtonhall%2Fcontentful-nextjs-headless","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsethburtonhall%2Fcontentful-nextjs-headless","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsethburtonhall%2Fcontentful-nextjs-headless/lists"}