From 0bb237944f290a8cd8a822176feb263b287da5d2 Mon Sep 17 00:00:00 2001 From: Abhinav Date: Sun, 6 Jul 2025 17:54:31 +0200 Subject: [PATCH 1/6] add pr-validation --- .github/ISSUE_TEMPLATE/bug_report.md | 32 +++++------ .github/ISSUE_TEMPLATE/feature_request.md | 19 ++++--- .github/PULL_REQUEST_TEMPLATE.md | 66 ++++++++++++----------- .github/workflows/markdown-lint.yml | 22 ++++++++ 4 files changed, 84 insertions(+), 55 deletions(-) create mode 100644 .github/workflows/markdown-lint.yml diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 126953f..de602ea 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,26 +1,26 @@ --- -name: Bug report -about: Create a report to help us improve -title: '' +name: Bug Report +about: Report an issue or inaccuracy in the documentation or guidelines. +title: "[Bug]: Short description of the bug" labels: bug assignees: '' --- -**Describe the bug** -A clear and concise description of what the bug is. +## Describe the Bug +A clear and concise description of what the bug or inaccuracy is. This could be a typo, incorrect information, a broken link, or a misleading instruction. -**To Reproduce** -Steps to reproduce the behavior: -1. Go to '...' -2. Click on '...' -3. See error +## To Reproduce +Steps to reproduce the behavior (if applicable): +1. Go to '[Page/File Name]' +2. Navigate to '[Section/Line Number]' +3. See '[Specific Issue]' -**Expected behavior** -A clear and concise description of what you expected to happen. +## Expected Behavior +A clear and concise description of what you expected to happen or what the correct information should be. -**Screenshots** -If applicable, add screenshots to help explain your problem. +## Screenshots +If applicable, add screenshots to help explain the problem (e.g., broken link, formatting issue). -**Additional context** -Add any other context about the problem here. \ No newline at end of file +## Additional Context +Add any other context about the problem here (e.g., browser, device, specific tool version if relevant to an instruction). diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index bdad32a..19a4b75 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,15 +1,20 @@ --- -name: Feature request -about: Suggest an idea for this project -title: '' +name: Feature Request +about: Suggest an idea for new content, guidelines, or improvements to the kit. +title: "[Feature]: Short description of the feature" labels: enhancement assignees: '' --- -**Is your feature request related to a problem? Please describe.** +## Is your feature request related to a problem? Please describe. +A clear and concise description of what the problem is. (e.g., "The current React guidelines don't cover state management with Zustand, which is a common pattern.") -**Describe the solution you'd like** +## Describe the Solution You'd Like +A clear and concise description of what you want to happen. (e.g., "Add a new guideline file for Zustand state management in the React section.") -**Additional context** -Add any other context or screenshots about the feature request here. \ No newline at end of file +## Describe Alternatives You've Considered +A clear and concise description of any alternative solutions or features you've considered. + +## Additional Context +Add any other context or screenshots about the feature request here. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 40c6a54..e0cc0fa 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,48 +1,50 @@ -# Pull Request Template ๐Ÿš€ - -## Description - -Please include a summary of the changes and the related issue. -Also, describe the motivation behind these changes and how they address the problem. - -Fixes #(issue number) - --- - -## Type of change - -- [ ] Bug fix (non-breaking change which fixes an issue) -- [ ] New feature (non-breaking change which adds functionality) -- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) -- [ ] Documentation update +name: Pull Request +about: Propose changes to the Code Instructions Kit +title: "[TYPE]: Short description of changes" +labels: '' +assignees: '' --- -## Checklist +## Pull Request Checklist -- [ ] My code follows the style guidelines of this project -- [ ] I have performed a self-review of my own code -- [ ] I have commented my code, particularly in hard-to-understand areas -- [ ] I have made corresponding changes to the documentation -- [ ] My changes generate no new warnings -- [ ] I have added tests that prove my fix is effective or that my feature works -- [ ] New and existing tests pass locally with my changes +Please ensure you have completed the following steps before submitting your pull request. This helps us review and merge your changes efficiently. ---- +### General Checks +- [ ] I have read the [CONTRIBUTING.md](https://github.com/abhinavkumar985/code-instructions-kit/blob/main/CONTRIBUTING.md) guidelines. +- [ ] My changes are clearly described below. +- [ ] My changes are focused on a single concern (e.g., one feature, one bug fix, one set of related documentation updates). + +### Content & Documentation Checks +- [ ] My changes are accurate and up-to-date. +- [ ] The language used is clear, concise, and professional. +- [ ] I have checked for any typos, grammatical errors, or spelling mistakes. +- [ ] All new or modified Markdown files (`.md`) adhere to consistent formatting (e.g., heading levels, list styles, code block formatting). +- [ ] If I added new guideline files (e.g., in `.gemini-guidelines/`), I have updated the corresponding `GEMINI.md` file to reference them. +- [ ] If I modified existing guideline files, I have ensured that any references to them in `GEMINI.md` are still accurate. +- [ ] All internal and external links within the modified content are valid and working. -## How Has This Been Tested? +### Specific to `GEMINI.md` and `.gemini-guidelines` +- [ ] If adding a new stack/framework, I have created both the `GEMINI.md` and the `.gemini-guidelines/` directory with at least an `overview.md`. +- [ ] I have ensured that the `GEMINI.md` file correctly references all files within its `.gemini-guidelines/` directory using the `.gemini-guidelines/filename.md` format. -Please describe the tests that you ran to verify your changes. -Include details on how to reproduce and test this. +### Self-Review +- [ ] I have reviewed my own code/content changes. +- [ ] I have tested any instructions or examples I've added to ensure they work as described. --- -## Screenshots (if applicable) +## Description of Changes -Add screenshots to help explain your changes here. +Please provide a detailed description of your changes here. Explain the problem you're solving, the feature you're adding, or the documentation you're improving. + +*(Example: "This PR adds new guidelines for Python FastAPI, including API design and data validation. It also updates the main README to reflect the new stack.")* --- -## Additional Notes +## Related Issues (Optional) + +If this PR addresses any open issues, please link them here (e.g., `Closes #123`). -Anything else reviewers should know about this PR. +--- \ No newline at end of file diff --git a/.github/workflows/markdown-lint.yml b/.github/workflows/markdown-lint.yml new file mode 100644 index 0000000..332209a --- /dev/null +++ b/.github/workflows/markdown-lint.yml @@ -0,0 +1,22 @@ +name: Markdown Lint + +on: + pull_request: + branches: + - main # Or your default branch name + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Install markdownlint-cli + run: npm install -g markdownlint-cli2 + + - name: Run markdownlint + run: markdownlint-cli2 "**/*.md" "#node_modules" "#.git" + # You can add a configuration file for markdownlint-cli2 if needed, + # e.g., .markdownlint.jsonc at the root of your repo. + # Example: markdownlint-cli2 --config .markdownlint.jsonc "**/*.md" From 4226c73f7d8fcc57bdfe7fb2410af7fb17c9f1d0 Mon Sep 17 00:00:00 2001 From: Abhinav Kumar Date: Sun, 6 Jul 2025 18:09:43 +0200 Subject: [PATCH 2/6] Update .github/PULL_REQUEST_TEMPLATE.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- .github/PULL_REQUEST_TEMPLATE.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index e0cc0fa..5029f48 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -2,6 +2,13 @@ name: Pull Request about: Propose changes to the Code Instructions Kit title: "[TYPE]: Short description of changes" + labels: '' assignees: '' From 8451085c5b35b3f8507b574052e9c19cd2e846ea Mon Sep 17 00:00:00 2001 From: Abhinav Kumar Date: Sun, 6 Jul 2025 18:10:01 +0200 Subject: [PATCH 3/6] Update .github/PULL_REQUEST_TEMPLATE.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5029f48..06e41f1 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -19,7 +19,7 @@ assignees: '' Please ensure you have completed the following steps before submitting your pull request. This helps us review and merge your changes efficiently. ### General Checks -- [ ] I have read the [CONTRIBUTING.md](https://github.com/abhinavkumar985/code-instructions-kit/blob/main/CONTRIBUTING.md) guidelines. +- [ ] I have read the [CONTRIBUTING.md](../CONTRIBUTING.md) guidelines. - [ ] My changes are clearly described below. - [ ] My changes are focused on a single concern (e.g., one feature, one bug fix, one set of related documentation updates). From 2583ba41da83f873957bc6f69a70ff0bbc97f3ce Mon Sep 17 00:00:00 2001 From: Abhinav Date: Sun, 6 Jul 2025 18:24:56 +0200 Subject: [PATCH 4/6] add markdown --- .github/ISSUE_TEMPLATE/bug_report.md | 21 +- .github/ISSUE_TEMPLATE/feature_request.md | 19 +- .github/workflows/markdown-lint.yml | 2 +- .markdownlint.jsonc | 38 ++++ .prettierrc.json | 6 + CONTRIBUTING.md | 47 +++-- README.md | 197 ++++++++++++------ angular/GEMINI.md | 46 ++-- examples/react/no-guidelines/README.md | 48 +++-- examples/react/with-guidelines/README.md | 71 +++++-- nextjs/.gemini-guidelines/api-routes.md | 21 +- .../app-router-structure.md | 25 ++- nextjs/.gemini-guidelines/overview.md | 49 +++-- .../.gemini-guidelines/seo-best-practices.md | 18 +- nextjs/.gemini-guidelines/testing.md | 20 +- nextjs/GEMINI.md | 54 +++-- node/.gemini-guidelines/async-patterns.md | 14 +- node/.gemini-guidelines/error-handling.md | 11 +- node/.gemini-guidelines/overview.md | 51 +++-- node/.gemini-guidelines/security.md | 17 +- node/GEMINI.md | 47 +++-- react/.gemini-guidelines/component-design.md | 25 ++- .../hooks-best-practices.md | 19 +- react/.gemini-guidelines/overview.md | 56 +++-- react/.gemini-guidelines/state-management.md | 20 +- react/.gemini-guidelines/testing.md | 16 +- react/GEMINI.md | 54 +++-- rule.json | 63 ++++++ shared-guidelines/accessibility.md | 59 ++++-- shared-guidelines/code-style.md | 55 +++-- shared-guidelines/performance.md | 46 ++-- shared-guidelines/testing-strategy.md | 48 +++-- .../islands-and-client-directives.md | 31 ++- .../.gemini-guidelines/overview.md | 33 ++- stacks/astro-vue-tailwind/GEMINI.md | 42 ++-- .../.gemini-guidelines/api-design.md | 15 +- .../database-interaction.md | 19 +- .../.gemini-guidelines/error-handling.md | 19 +- .../.gemini-guidelines/overview.md | 50 +++-- stacks/node-express/GEMINI.md | 45 ++-- .../.gemini-guidelines/api-design.md | 21 +- .../.gemini-guidelines/data-validation.md | 15 +- .../dependency-injection.md | 16 +- .../.gemini-guidelines/overview.md | 59 +++--- stacks/python-fastapi/GEMINI.md | 57 ++--- .../.gemini-guidelines/overview.md | 38 +++- .../server-client-components.md | 23 +- stacks/react-next-tailwind/GEMINI.md | 42 ++-- .../data-loading-form-actions.md | 17 +- .../.gemini-guidelines/overview.md | 35 ++-- stacks/sveltekit-tailwind/GEMINI.md | 42 ++-- .../.gemini-guidelines/composables.md | 13 +- .../.gemini-guidelines/overview.md | 33 ++- stacks/vue-vite-pinia/GEMINI.md | 41 ++-- .../.gemini-guidelines/component-structure.md | 10 +- svelte/.gemini-guidelines/overview.md | 48 +++-- svelte/.gemini-guidelines/reactivity-guide.md | 15 +- svelte/GEMINI.md | 44 ++-- tailwind/.gemini-guidelines/overview.md | 36 ++-- tailwind/.gemini-guidelines/theming.md | 19 +- .../utility-class-patterns.md | 25 +-- tailwind/GEMINI.md | 44 ++-- typescript/.gemini-guidelines/overview.md | 28 ++- .../.gemini-guidelines/tsconfig-guide.md | 18 +- .../types-best-practices.md | 22 +- typescript/GEMINI.md | 44 ++-- vue/.gemini-guidelines/composition-api.md | 19 +- vue/.gemini-guidelines/file-structure.md | 26 +-- vue/.gemini-guidelines/overview.md | 44 ++-- vue/.gemini-guidelines/vuex-vs-pinia.md | 12 +- vue/GEMINI.md | 47 +++-- 71 files changed, 1638 insertions(+), 852 deletions(-) create mode 100644 .markdownlint.jsonc create mode 100644 .prettierrc.json create mode 100644 rule.json diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index de602ea..f1c1544 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,26 +1,35 @@ --- name: Bug Report about: Report an issue or inaccuracy in the documentation or guidelines. -title: "[Bug]: Short description of the bug" +title: '[Bug]: Short description of the bug' labels: bug assignees: '' - --- ## Describe the Bug -A clear and concise description of what the bug or inaccuracy is. This could be a typo, incorrect information, a broken link, or a misleading instruction. + +A clear and concise description of what the bug or inaccuracy is. This could be +a typo, incorrect information, a broken link, or a misleading instruction. ## To Reproduce + Steps to reproduce the behavior (if applicable): + 1. Go to '[Page/File Name]' 2. Navigate to '[Section/Line Number]' 3. See '[Specific Issue]' ## Expected Behavior -A clear and concise description of what you expected to happen or what the correct information should be. + +A clear and concise description of what you expected to happen or what the +correct information should be. ## Screenshots -If applicable, add screenshots to help explain the problem (e.g., broken link, formatting issue). + +If applicable, add screenshots to help explain the problem (e.g., broken link, +formatting issue). ## Additional Context -Add any other context about the problem here (e.g., browser, device, specific tool version if relevant to an instruction). + +Add any other context about the problem here (e.g., browser, device, specific +tool version if relevant to an instruction). diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 19a4b75..89de4c4 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,20 +1,27 @@ --- name: Feature Request about: Suggest an idea for new content, guidelines, or improvements to the kit. -title: "[Feature]: Short description of the feature" +title: '[Feature]: Short description of the feature' labels: enhancement assignees: '' - --- -## Is your feature request related to a problem? Please describe. -A clear and concise description of what the problem is. (e.g., "The current React guidelines don't cover state management with Zustand, which is a common pattern.") +## **Is your feature request related to a problem? Please describe** + +A clear and concise description of what the problem is. (e.g., "The current +React guidelines don't cover state management with Zustand, which is a common +pattern.") ## Describe the Solution You'd Like -A clear and concise description of what you want to happen. (e.g., "Add a new guideline file for Zustand state management in the React section.") + +A clear and concise description of what you want to happen. (e.g., "Add a new +guideline file for Zustand state management in the React section.") ## Describe Alternatives You've Considered -A clear and concise description of any alternative solutions or features you've considered. + +A clear and concise description of any alternative solutions or features you've +considered. ## Additional Context + Add any other context or screenshots about the feature request here. diff --git a/.github/workflows/markdown-lint.yml b/.github/workflows/markdown-lint.yml index 332209a..a701b97 100644 --- a/.github/workflows/markdown-lint.yml +++ b/.github/workflows/markdown-lint.yml @@ -16,7 +16,7 @@ jobs: run: npm install -g markdownlint-cli2 - name: Run markdownlint - run: markdownlint-cli2 "**/*.md" "#node_modules" "#.git" + run: markdownlint-cli2 --config .markdownlint.jsonc "**/*.md" "#node_modules" "#.git # You can add a configuration file for markdownlint-cli2 if needed, # e.g., .markdownlint.jsonc at the root of your repo. # Example: markdownlint-cli2 --config .markdownlint.jsonc "**/*.md" diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc new file mode 100644 index 0000000..de348f8 --- /dev/null +++ b/.markdownlint.jsonc @@ -0,0 +1,38 @@ +// .markdownlint.jsonc +{ + // MD007: Unordered list indentation (list-marker-space) + // Disable this as Prettier handles list formatting and may use 2 spaces. + "MD007": false, + "list-marker-space": false, + // MD013: Line length + // Disable this for prose as Prettier's "proseWrap: always" handles wrapping, + // and strict line limits can make documentation hard to read. + "MD013": false, + "line-length": false, + "MD031": false, + "MD032": false, + // MD026: Trailing punctuation in heading + // This is a good rule to enforce for clean headings. We will fix these. + "MD026": true, + // MD034: Bare URL used + // This is a good rule to enforce for readability. We will fix these. + "MD034": true, + // MD040: Fenced code blocks should have a language specified + // This is important for syntax highlighting. We will fix these. + "MD040": true, + // MD041: First line in a file should be a top-level heading + // This is a good practice for READMEs. We will fix this. + "MD041": true, + // MD024: Multiple headings with the same content + // This indicates a structural issue. We will fix this. + "MD024": true, + // MD038: Spaces inside code span elements + // This is a formatting issue. We will fix this. + "MD038": true, + // MD047: Files should end with a single newline character + // Good practice, Prettier should handle this. + "MD047": true, + // MD012: Multiple blank lines + // Good practice, Prettier should help with this. + "MD012": true +} \ No newline at end of file diff --git a/.prettierrc.json b/.prettierrc.json new file mode 100644 index 0000000..da21d72 --- /dev/null +++ b/.prettierrc.json @@ -0,0 +1,6 @@ +{ + "singleQuote": true, + "trailingComma": "all", + "printWidth": 80, + "proseWrap": "always" +} \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 52ec6e9..8ef47fb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,38 +1,47 @@ # ๐Ÿ› ๏ธ Contributing to Code Instructions Kit -Thank you for your interest in contributing! This repository shares high-quality, framework-specific, and stack-specific coding prompts and guidelines designed to help developers write better, cleaner, and more maintainable frontend code using Gemini CLI. +Thank you for your interest in contributing! This repository shares +high-quality, framework-specific, and stack-specific coding prompts and +guidelines designed to help developers write better, cleaner, and more +maintainable frontend code using Gemini CLI. ## How You Can Contribute -- โœ๏ธ **Add or improve instruction files** โ€” submit best practices, tips, or templates for popular frontend frameworks or stacks. -- ๐Ÿž **Fix typos or improve clarity** โ€” clear and concise instructions make the repo more valuable. -- ๐Ÿ’ก **Suggest new topics or frameworks** โ€” if you think something important is missing, open an issue or PR. -- ๐Ÿงช **Add examples** โ€” practical prompt vs. output markdowns help others understand real-world use. -- ๐Ÿš€ **Report bugs or issues** โ€” flag outdated or incorrect info. +- โœ๏ธ **Add or improve instruction files** โ€” submit best practices, tips, or + templates for popular frontend frameworks or stacks. +- ๐Ÿž **Fix typos or improve clarity** โ€” clear and concise instructions make the + repo more valuable. +- ๐Ÿ’ก **Suggest new topics or frameworks** โ€” if you think something important is + missing, open an issue or PR. +- ๐Ÿงช **Add examples** โ€” practical prompt vs. output markdowns help others + understand real-world use. +- ๐Ÿš€ **Report bugs or issues** โ€” flag outdated or incorrect info. ## Contribution Guidelines -- Follow existing folder and naming conventions. -- Write in clear, concise English. -- Use consistent markdown formatting. -- Be respectful and constructive in reviews and discussions. -- Keep instructions practical and actionable for Gemini CLI users. -- For major changes, open an issue to discuss before submitting a PR. +- Follow existing folder and naming conventions. +- Write in clear, concise English. +- Use consistent markdown formatting. +- Be respectful and constructive in reviews and discussions. +- Keep instructions practical and actionable for Gemini CLI users. +- For major changes, open an issue to discuss before submitting a PR. ## How to Submit -1. Fork the repository. -2. Create a new branch for your change. -3. Make your edits or add files. -4. Commit with clear messages. -5. Push your branch and open a Pull Request against the `main` branch. -6. Respond to feedback and collaborate during review. +1. Fork the repository. +2. Create a new branch for your change. +3. Make your edits or add files. +4. Commit with clear messages. +5. Push your branch and open a Pull Request against the `main` branch. +6. Respond to feedback and collaborate during review. --- ## Code of Conduct -This project follows a [Code of Conduct](https://opensource.guide/code-of-conduct/). Please be kind and respectful. +This project follows a +[Code of Conduct](https://opensource.guide/code-of-conduct/). Please be kind and +respectful. --- diff --git a/README.md b/README.md index 99a4d57..ef86375 100644 --- a/README.md +++ b/README.md @@ -1,108 +1,169 @@ -## ๐Ÿš€ Code Instructions Kit +# ๐Ÿš€ Code Instructions Kit -A curated collection of high-quality instruction templates and prompt guides to help developers write better code prompts โ€” especially for AI-powered coding assistants like Gemini CLI, GitHub Copilot, and more. +A curated collection of high-quality instruction templates and prompt guides to +help developers write better code prompts โ€” especially for AI-powered coding +assistants like Gemini CLI, GitHub Copilot, and more. -# โœจ Introduction -Welcome to Code Instructions Kit โ€” your go-to repository for well-crafted instruction templates aimed at improving developer workflows with AI coding tools. Whether you're using Gemini CLI or GitHub Copilot, writing clear and effective prompts can drastically enhance your productivity and code quality. +## โœจ Introduction -This repo provides framework-specific, best-practice instruction files that help you define coding style, component design patterns, testing strategies, and repository conventions โ€” so your AI coding assistant understands exactly what you expect. +Welcome to Code Instructions Kit โ€” your go-to repository for well-crafted +instruction templates aimed at improving developer workflows with AI coding +tools. Whether you're using Gemini CLI or GitHub Copilot, writing clear and +effective prompts can drastically enhance your productivity and code quality. -# ๐ŸŽฏ Motivation & Purpose -The rise of AI-assisted coding is reshaping software development, but the quality of output depends heavily on the quality of instructions and context provided. Unfortunately, crafting these prompts and instructions from scratch can be tedious and inconsistent across teams. +This repo provides framework-specific, best-practice instruction files that help +you define coding style, component design patterns, testing strategies, and +repository conventions โ€” so your AI coding assistant understands exactly what +you expect. + +## ๐ŸŽฏ Motivation & Purpose + +The rise of AI-assisted coding is reshaping software development, but the +quality of output depends heavily on the quality of instructions and context +provided. Unfortunately, crafting these prompts and instructions from scratch +can be tedious and inconsistent across teams. This project aims to: -- Provide ready-to-use, standardized instruction templates for popular frontend frameworks and tooling combinations (React, Next.js, Tailwind, Vue, Vite, etc.) +- Provide ready-to-use, standardized instruction templates for popular frontend + frameworks and tooling combinations (React, Next.js, Tailwind, Vue, Vite, + etc.) -- Share best practices distilled from industry experience for component design, testing, accessibility, and code style +- Share best practices distilled from industry experience for component design, + testing, accessibility, and code style -- Enable developers at all levels to accelerate their AI-assisted coding workflows with minimal setup +- Enable developers at all levels to accelerate their AI-assisted coding + workflows with minimal setup -- Foster a community-driven collection where contributors can share their own templates, improvements, and ideas +- Foster a community-driven collection where contributors can share their own + templates, improvements, and ideas -# ๐Ÿ’ก Use Cases: How This Kit Empowers Your Development Workflow +## ๐Ÿ’ก Use Cases: How This Kit Empowers Your Development Workflow -This kit is designed to seamlessly integrate into your projects, offering tangible benefits: +This kit is designed to seamlessly integrate into your projects, offering +tangible benefits: -- **Rapid AI Assistant Setup**: Quickly configure your AI coding assistant with battle-tested instruction files, ensuring it understands your project's specific conventions from day one. -- **Enforce Best Practices**: Leverage pre-defined templates to guide your AI in generating code that adheres to industry-standard component design, testing, and accessibility principles. -- **Tailored Code Generation**: Customize prompts and guidelines to precisely match your team's unique coding style, architectural patterns, and project-specific requirements, leading to more accurate and idiomatic AI-generated code. -- **Standardized Collaboration**: Establish a shared understanding of coding standards across your team, fostering consistency and reducing friction in open-source or enterprise projects. +- **Rapid AI Assistant Setup**: Quickly configure your AI coding assistant with + battle-tested instruction files, ensuring it understands your project's + specific conventions from day one. +- **Enforce Best Practices**: Leverage pre-defined templates to guide your AI in + generating code that adheres to industry-standard component design, testing, + and accessibility principles. +- **Tailored Code Generation**: Customize prompts and guidelines to precisely + match your team's unique coding style, architectural patterns, and + project-specific requirements, leading to more accurate and idiomatic + AI-generated code. +- **Standardized Collaboration**: Establish a shared understanding of coding + standards across your team, fostering consistency and reducing friction in + open-source or enterprise projects. -# ๐Ÿš€ Getting Started: Integrate This Kit into Your Project +## ๐Ÿš€ Getting Started: Integrate This Kit into Your Project -Follow these steps to empower your AI coding assistant with project-specific guidelines: +Follow these steps to empower your AI coding assistant with project-specific +guidelines: 1. **Clone the Repository**: + ```bash git clone https://github.com/abhinavkumar985/code-instructions-kit.git cd code-instructions-kit ``` -2. **Identify Your Stack**: Browse the folders (e.g., `react/`, `node/`, `stacks/react-next-tailwind/`) to find the `GEMINI.md` and `.gemini-guidelines/` directory that best matches your project's technology stack. +2. **Identify Your Stack**: Browse the folders (e.g., `react/`, `node/`, + `stacks/react-next-tailwind/`) to find the `GEMINI.md` and + `.gemini-guidelines/` directory that best matches your project's technology + stack. 3. **Integrate into Your Project**: - * **For New Projects**: Copy the entire `GEMINI.md` file and its corresponding `.gemini-guidelines/` directory directly into your new project's root folder. - * **For Existing Projects**: - * Copy the `GEMINI.md` file and the `.gemini-guidelines/` directory into your project's root. - * If you already have a `GEMINI.md` or similar configuration, merge the relevant sections from this kit's `GEMINI.md` into your existing one. Ensure the `.gemini-guidelines/` directory is placed alongside your `GEMINI.md` file. - - *Example Structure in Your Project Root:* - ``` - your-project/ - โ”œโ”€โ”€ GEMINI.md - โ”œโ”€โ”€ .gemini-guidelines/ - โ”‚ โ”œโ”€โ”€ overview.md - โ”‚ โ””โ”€โ”€ component-design.md - โ””โ”€โ”€ src/ - โ””โ”€โ”€ ... - ``` - -4. **Customize and Extend**: - * Open the copied `GEMINI.md` and the files within `.gemini-guidelines/`. - * Modify their content to reflect your project's unique coding standards, architectural decisions, and team preferences. This is crucial for tailoring the AI's output. - * Add new guideline files to `.gemini-guidelines/` as needed, and remember to reference them in your `GEMINI.md`. - -5. **Leverage with Your AI Assistant**: - * **For Gemini CLI**: The CLI automatically detects `GEMINI.md` and its referenced guidelines in your project root. Simply start interacting with the CLI, and it will use these instructions to inform its responses and code generation. - * **For Other AI Assistants (e.g., GitHub Copilot)**: Copy the relevant content from the `.gemini-guidelines/` files into your assistant's configuration or prompt context. - -# ๐Ÿ› ๏ธ Recommendations for Maximizing Value + - **For New Projects**: Copy the entire `GEMINI.md` file and its + corresponding `.gemini-guidelines/` directory directly into your new + project's root folder. + - **For Existing Projects**: + - Copy the `GEMINI.md` file and the `.gemini-guidelines/` directory into + your project's root. + - If you already have a `GEMINI.md` or similar configuration, merge the + relevant sections from this kit's `GEMINI.md` into your existing one. + Ensure the `.gemini-guidelines/` directory is placed alongside your + `GEMINI.md` file. + + _Example Structure in Your Project Root:_ + + ```your-project/ +โ”œโ”€โ”€ GEMINI.md +โ”œโ”€โ”€ .gemini-guidelines/ +โ”‚ โ”œโ”€โ”€ overview.md +โ”‚ โ””โ”€โ”€ component-design.md +โ””โ”€โ”€ src/ + โ””โ”€โ”€ ...``` + +1. **Customize and Extend**: + - Open the copied `GEMINI.md` and the files within `.gemini-guidelines/`. + - Modify their content to reflect your project's unique coding standards, + architectural decisions, and team preferences. This is crucial for + tailoring the AI's output. + - Add new guideline files to `.gemini-guidelines/` as needed, and remember + to reference them in your `GEMINI.md`. + +2. **Leverage with Your AI Assistant**: + - **For Gemini CLI**: The CLI automatically detects `GEMINI.md` and its + referenced guidelines in your project root. Simply start interacting with + the CLI, and it will use these instructions to inform its responses and + code generation. + - **For Other AI Assistants (e.g., GitHub Copilot)**: Copy the relevant + content from the `.gemini-guidelines/` files into your assistant's + configuration or prompt context. + +## ๐Ÿ› ๏ธ Recommendations for Maximizing Value To get the most out of this kit and your AI coding assistant: -- **Adapt, Don't Just Adopt**: Treat these templates as robust starting points. Actively customize them to precisely fit your project's unique context, team culture, and technical requirements. -- **Maintain as a Living Document**: Your codebase evolves, and so should your guidelines. Regularly review and update your `GEMINI.md` and `.gemini-guidelines/` files to reflect changes in your project's architecture, dependencies, or best practices. -- **Contribute Back**: Your improvements and new templates are invaluable! Share them with the community via Pull Requests to help this resource grow and benefit others. -- **Stay Updated**: Follow this repository to receive notifications on new additions, updated best practices, and enhancements to the kit. - -# ๐Ÿค Contributing - -We welcome and encourage contributions from the community! Your insights and additions are vital to making this kit a comprehensive and invaluable resource for developers. +- **Adapt, Don't Just Adopt**: Treat these templates as robust starting points. + Actively customize them to precisely fit your project's unique context, team + culture, and technical requirements. +- **Maintain as a Living Document**: Your codebase evolves, and so should your + guidelines. Regularly review and update your `GEMINI.md` and + `.gemini-guidelines/` files to reflect changes in your project's architecture, + dependencies, or best practices. +- **Contribute Back**: Your improvements and new templates are invaluable! Share + them with the community via Pull Requests to help this resource grow and + benefit others. +- **Stay Updated**: Follow this repository to receive notifications on new + additions, updated best practices, and enhancements to the kit. + +## ๐Ÿค Contributing + +We welcome and encourage contributions from the community! Your insights and +additions are vital to making this kit a comprehensive and invaluable resource +for developers. If you have: -- Instruction templates for other frameworks, libraries, or tooling combinations. -- Improvements or refinements for existing files. -- Suggestions for new sections, topics, or best practices. +- Instruction templates for other frameworks, libraries, or tooling + combinations. +- Improvements or refinements for existing files. +- Suggestions for new sections, topics, or best practices. + +Please open an issue or submit a pull request. Let's collaborate to build the +ultimate resource for AI-assisted coding! -Please open an issue or submit a pull request. Let's collaborate to build the ultimate resource for AI-assisted coding! +## ๐Ÿ“„ License -# ๐Ÿ“„ License This project is open source under the MIT License. -# ๐Ÿ”— Connect & Follow -If you find this repo helpful, please โญ star it and share it with your developer network. -Follow me for more insights on frontend development, AI tools, and open source contributions. +## ๐Ÿ”— Connect & Follow + +If you find this repo helpful, please โญ star it and share it with your +developer network. Follow me for more insights on frontend development, AI +tools, and open source contributions. -๐Ÿ™ GitHub: https://github.com/abhinavkumar985 +๐Ÿ™ GitHub: [https://github.com/abhinavkumar985](https://github.com/abhinavkumar985) -๐Ÿฆ Twitter: https://x.com/abhinav985 +๐Ÿฆ Twitter: [https://x.com/abhinav985](https://x.com/abhinav985) -๐Ÿ’ผ LinkedIn: https://www.linkedin.com/in/abhinavkumar985/ +๐Ÿ’ผ LinkedIn: [https://www.linkedin.com/in/abhinavkumar985/](https://www.linkedin.com/in/abhinavkumar985/) -๐ŸŒ Portfolio: https://abhinavkumar985.github.io/portfolio/about +๐ŸŒ Portfolio: [https://abhinavkumar985.github.io/portfolio/about](https://abhinavkumar985.github.io/portfolio/about) -โœ๏ธ Medium: https://medium.com/@abhinavkumar985 +โœ๏ธ Medium: [https://medium.com/@abhinavkumar985](https://medium.com/@abhinavkumar985) -Thank you for visiting Code Instructions Kit โ€” happy coding! ๐ŸŽ‰ \ No newline at end of file +Thank you for visiting Code Instructions Kit โ€” happy coding! ๐ŸŽ‰ diff --git a/angular/GEMINI.md b/angular/GEMINI.md index 3e17d48..f43b269 100644 --- a/angular/GEMINI.md +++ b/angular/GEMINI.md @@ -2,32 +2,46 @@ ## Project Introduction -This project is a **TODO List Application** built to demonstrate modern web development practices. It allows users to manage their daily tasks efficiently, providing a clear and intuitive interface for adding, completing, and deleting to-do items. +This project is a **TODO List Application** built to demonstrate modern web +development practices. It allows users to manage their daily tasks efficiently, +providing a clear and intuitive interface for adding, completing, and deleting +to-do items. ## Core Features -* **Add New Todos**: Quickly add new tasks to the list. -* **Mark Todos as Complete**: Toggle the completion status of tasks. -* **Delete Todos**: Remove unwanted tasks from the list. -* **Filter Todos**: View all, active, or completed tasks. -* **Persistence**: Todos are saved and loaded (e.g., from local storage or a backend API). +- **Add New Todos**: Quickly add new tasks to the list. +- **Mark Todos as Complete**: Toggle the completion status of tasks. +- **Delete Todos**: Remove unwanted tasks from the list. +- **Filter Todos**: View all, active, or completed tasks. +- **Persistence**: Todos are saved and loaded (e.g., from local storage or a + backend API). ## Build and Deployment To set up and run this application: -1. **Install Dependencies**: Run `npm install` or `yarn install` in the project root. -2. **Run Development Server**: Execute `ng serve` to start the development server. The application will be accessible at `http://localhost:4200`. -3. **Build for Production**: Run `ng build` to create an optimized production build. -4. **Start Production Server**: Execute `serve -s dist` (after installing `serve` globally) to serve the production build. +1. **Install Dependencies**: Run `npm install` or `yarn install` in the project + root. +2. **Run Development Server**: Execute `ng serve` to start the development + server. The application will be accessible at `http://localhost:4200`. +3. **Build for Production**: Run `ng build` to create an optimized production + build. +4. **Start Production Server**: Execute `serve -s dist` (after installing + `serve` globally) to serve the production build. --- -This project is an **Angular** frontend application, built with TypeScript and following Angular's component-based architecture. It emphasizes modularity, reusability, and type safety. +This project is an **Angular** frontend application, built with TypeScript and +following Angular's component-based architecture. It emphasizes modularity, +reusability, and type safety. -## Key Instructions & Guidelines: +## Key Instructions & Guidelines -* **General Instructions**: See `.gemini-guidelines/overview.md` for core principles and tasks. -* **Module Structure**: See `.gemini-guidelines/module-structure.md` for organizing Angular modules. -* **Service Injection**: See `.gemini-guidelines/service-injection.md` for guidelines on dependency injection. -* **Testing Strategy**: See `.gemini-guidelines/testing.md` for testing guidelines. +- **General Instructions**: See `.gemini-guidelines/overview.md` for core + principles and tasks. +- **Module Structure**: See `.gemini-guidelines/module-structure.md` for + organizing Angular modules. +- **Service Injection**: See `.gemini-guidelines/service-injection.md` for + guidelines on dependency injection. +- **Testing Strategy**: See `.gemini-guidelines/testing.md` for testing + guidelines. diff --git a/examples/react/no-guidelines/README.md b/examples/react/no-guidelines/README.md index 6a87b2f..ecf5622 100644 --- a/examples/react/no-guidelines/README.md +++ b/examples/react/no-guidelines/README.md @@ -1,25 +1,41 @@ # Components Generated Without Specific Guidelines -This directory contains React components (`Product.tsx`, `ProductList.tsx`, `Cart.tsx`) and a custom hook (`useCart.ts`) that were generated with minimal, generic instructions provided to an AI coding assistant. The purpose is to simulate a scenario where the AI lacks specific project context, coding standards, or best practice guidelines. +This directory contains React components (`Product.tsx`, `ProductList.tsx`, +`Cart.tsx`) and a custom hook (`useCart.ts`) that were generated with minimal, +generic instructions provided to an AI coding assistant. The purpose is to +simulate a scenario where the AI lacks specific project context, coding +standards, or best practice guidelines. ## How These Components Were Generated -The AI was simply asked to create these components with basic functional requirements, without any explicit instructions regarding: +The AI was simply asked to create these components with basic functional +requirements, without any explicit instructions regarding: -* Specific component design patterns (e.g., container/presentational). -* Detailed TypeScript typing conventions beyond basic prop interfaces. -* React Hooks best practices (e.g., `useCallback`, `useMemo` for optimization). -* Styling methodology (e.g., Tailwind CSS, CSS Modules). -* Code structure, naming conventions, or documentation standards. +- Specific component design patterns (e.g., container/presentational). +- Detailed TypeScript typing conventions beyond basic prop interfaces. +- React Hooks best practices (e.g., `useCallback`, `useMemo` for optimization). +- Styling methodology (e.g., Tailwind CSS, CSS Modules). +- Code structure, naming conventions, or documentation standards. ## What You'll Observe (Major Lacks) -Upon reviewing the code in this folder, you'll notice several areas where the absence of guidelines is apparent: - -* **Basic Typing**: While TypeScript is used, the type definitions are often minimal and might not be as robust or explicit as they could be for complex data structures or callbacks. -* **Inconsistent Styling**: Styling is done using basic inline styles, which is not scalable or maintainable for larger applications. There's no consistent design system. -* **Lack of Advanced Hook Usage**: Custom hooks might be functional but may not leverage advanced React features like `useCallback` or `useMemo` for performance optimization, potentially leading to unnecessary re-renders. -* **General Component Structure**: Components are functional but may not strictly adhere to principles like Single Responsibility or clear separation of concerns. -* **Limited Documentation**: Code comments and JSDoc are sparse or absent, making the code harder to understand and maintain for other developers. - -This serves as a baseline to demonstrate the impact of providing comprehensive guidelines to an AI assistant. \ No newline at end of file +Upon reviewing the code in this folder, you'll notice several areas where the +absence of guidelines is apparent: + +- **Basic Typing**: While TypeScript is used, the type definitions are often + minimal and might not be as robust or explicit as they could be for complex + data structures or callbacks. +- **Inconsistent Styling**: Styling is done using basic inline styles, which is + not scalable or maintainable for larger applications. There's no consistent + design system. +- **Lack of Advanced Hook Usage**: Custom hooks might be functional but may not + leverage advanced React features like `useCallback` or `useMemo` for + performance optimization, potentially leading to unnecessary re-renders. +- **General Component Structure**: Components are functional but may not + strictly adhere to principles like Single Responsibility or clear separation + of concerns. +- **Limited Documentation**: Code comments and JSDoc are sparse or absent, + making the code harder to understand and maintain for other developers. + +This serves as a baseline to demonstrate the impact of providing comprehensive +guidelines to an AI assistant. diff --git a/examples/react/with-guidelines/README.md b/examples/react/with-guidelines/README.md index 103ca48..0d948bd 100644 --- a/examples/react/with-guidelines/README.md +++ b/examples/react/with-guidelines/README.md @@ -1,31 +1,56 @@ # Components Generated With Specific Guidelines -This directory contains React components (`Product.tsx`, `ProductList.tsx`, `Cart.tsx`) and a custom hook (`useCart.ts`) that were generated with the explicit context of detailed project guidelines. The purpose is to demonstrate how providing comprehensive instructions to an AI coding assistant leads to higher quality, more maintainable, and standard-compliant code. +This directory contains React components (`Product.tsx`, `ProductList.tsx`, +`Cart.tsx`) and a custom hook (`useCart.ts`) that were generated with the +explicit context of detailed project guidelines. The purpose is to demonstrate +how providing comprehensive instructions to an AI coding assistant leads to +higher quality, more maintainable, and standard-compliant code. ## How These Components Were Generated -Before generating these components, the AI assistant was provided with and instructed to adhere to the following guidelines from the `code-instructions-kit`: - -* **React Guidelines**: (`react/GEMINI.md` and its `.gemini-guidelines` sub-files) - * Component Design Principles (e.g., Single Responsibility, Container/Presentational separation). - * React Hooks Best Practices (e.g., `useCallback`, `useMemo`, proper dependency arrays). - * State Management patterns (e.g., `useState`, `useContext`). -* **TypeScript Guidelines**: (`typescript/GEMINI.md` and its `.gemini-guidelines` sub-files) - * Strong type safety and explicit interface definitions. - * Idiomatic TypeScript usage. -* **Tailwind CSS Guidelines**: (`tailwind/GEMINI.md` and its `.gemini-guidelines` sub-files) - * Utility-first approach for styling. - * Consistent application of Tailwind classes. +Before generating these components, the AI assistant was provided with and +instructed to adhere to the following guidelines from the +`code-instructions-kit`: + +- **React Guidelines**: (`react/GEMINI.md` and its `.gemini-guidelines` + sub-files) + - Component Design Principles (e.g., Single Responsibility, + Container/Presentational separation). + - React Hooks Best Practices (e.g., `useCallback`, `useMemo`, proper + dependency arrays). + - State Management patterns (e.g., `useState`, `useContext`). +- **TypeScript Guidelines**: (`typescript/GEMINI.md` and its + `.gemini-guidelines` sub-files) + - Strong type safety and explicit interface definitions. + - Idiomatic TypeScript usage. +- **Tailwind CSS Guidelines**: (`tailwind/GEMINI.md` and its + `.gemini-guidelines` sub-files) + - Utility-first approach for styling. + - Consistent application of Tailwind classes. ## What You'll Observe (Major Improvements) -Upon reviewing the code in this folder, you'll notice significant improvements due to the application of these guidelines: - -* **Robust Typing**: Comprehensive and explicit TypeScript interfaces for props, state, and data structures, ensuring strong type safety and better developer experience. -* **Idiomatic React Patterns**: Components follow established React patterns, such as functional components with hooks, clear prop drilling, and separation of concerns. -* **Optimized Hooks Usage**: Custom hooks (like `useCart`) leverage `useCallback` and other optimization techniques to prevent unnecessary re-renders and improve performance. -* **Consistent Styling with Tailwind CSS**: All styling is applied using Tailwind CSS utility classes, demonstrating a scalable and maintainable styling approach consistent with modern web development practices. -* **Improved Readability and Maintainability**: Code is generally cleaner, more organized, and includes meaningful JSDoc comments for functions and interfaces, making it easier to understand and maintain. -* **Clear Separation of Concerns**: Components are designed with a single responsibility in mind, leading to more modular and reusable code. - -This folder serves as a prime example of how a well-defined set of instructions can elevate the quality of AI-generated code, making it production-ready and aligned with project standards. \ No newline at end of file +Upon reviewing the code in this folder, you'll notice significant improvements +due to the application of these guidelines: + +- **Robust Typing**: Comprehensive and explicit TypeScript interfaces for props, + state, and data structures, ensuring strong type safety and better developer + experience. +- **Idiomatic React Patterns**: Components follow established React patterns, + such as functional components with hooks, clear prop drilling, and separation + of concerns. +- **Optimized Hooks Usage**: Custom hooks (like `useCart`) leverage + `useCallback` and other optimization techniques to prevent unnecessary + re-renders and improve performance. +- **Consistent Styling with Tailwind CSS**: All styling is applied using + Tailwind CSS utility classes, demonstrating a scalable and maintainable + styling approach consistent with modern web development practices. +- **Improved Readability and Maintainability**: Code is generally cleaner, more + organized, and includes meaningful JSDoc comments for functions and + interfaces, making it easier to understand and maintain. +- **Clear Separation of Concerns**: Components are designed with a single + responsibility in mind, leading to more modular and reusable code. + +This folder serves as a prime example of how a well-defined set of instructions +can elevate the quality of AI-generated code, making it production-ready and +aligned with project standards. diff --git a/nextjs/.gemini-guidelines/api-routes.md b/nextjs/.gemini-guidelines/api-routes.md index bf29582..2a13d0d 100644 --- a/nextjs/.gemini-guidelines/api-routes.md +++ b/nextjs/.gemini-guidelines/api-routes.md @@ -1,12 +1,14 @@ - # API Routes (Route Handlers) Use Route Handlers for creating API endpoints within the App Router. ## โœ… **Instructions** -1. **File Location**: Create a `route.ts` file inside the desired API path (e.g., `/app/api/users/route.ts`). -2. **HTTP Methods**: Export named functions for each HTTP method (`GET`, `POST`, `PUT`, `DELETE`). +1. **File Location**: Create a `route.ts` file inside the desired API path + (e.g., `/app/api/users/route.ts`). + +2. **HTTP Methods**: Export named functions for each HTTP method (`GET`, + `POST`, `PUT`, `DELETE`). ```typescript // /app/api/users/route.ts @@ -24,13 +26,15 @@ Use Route Handlers for creating API endpoints within the App Router. } ``` -3. **Dynamic Routes**: Use square brackets `[folderName]` to create dynamic API routes. +3. **Dynamic Routes**: Use square brackets `[folderName]` to create dynamic API + routes. - ``` + ```text /app/api/users/[id]/route.ts ``` -4. **Error Handling**: Wrap your logic in `try...catch` blocks to handle potential errors and return appropriate error responses. +4. **Error Handling**: Wrap your logic in `try...catch` blocks to handle + potential errors and return appropriate error responses. ```typescript export async function GET(request: Request) { @@ -38,7 +42,10 @@ Use Route Handlers for creating API endpoints within the App Router. // Your logic here return NextResponse.json({ success: true }); } catch (error) { - return NextResponse.json({ error: 'Something went wrong' }, { status: 500 }); + return NextResponse.json( + { error: 'Something went wrong' }, + { status: 500 }, + ); } } ``` diff --git a/nextjs/.gemini-guidelines/app-router-structure.md b/nextjs/.gemini-guidelines/app-router-structure.md index 96791e4..f9d348c 100644 --- a/nextjs/.gemini-guidelines/app-router-structure.md +++ b/nextjs/.gemini-guidelines/app-router-structure.md @@ -1,20 +1,19 @@ - # App Router Structure Follow this structure for organizing files within the `/app` directory. ## ๐Ÿ“‚ **File Naming and Colocation** -- **`page.tsx`**: The main UI for a route. -- **`layout.tsx`**: The UI shell shared across multiple routes. -- **`loading.tsx`**: A loading indicator for the route. -- **`error.tsx`**: An error boundary for the route. -- **`template.tsx`**: A re-rendering layout on navigation. -- **`route.ts`**: API endpoint (Route Handler). +- **`page.tsx`**: The main UI for a route. +- **`layout.tsx`**: The UI shell shared across multiple routes. +- **`loading.tsx`**: A loading indicator for the route. +- **`error.tsx`**: An error boundary for the route. +- **`template.tsx`**: A re-rendering layout on navigation. +- **`route.ts`**: API endpoint (Route Handler). ## Example: Blog Post Route -``` +```text /app /blog /[slug] @@ -26,6 +25,10 @@ Follow this structure for organizing files within the `/app` directory. ## โœ… **Instructions** -- **Colocate Components**: Place route-specific components, such as a ``, in the same directory as the `page.tsx` file. -- **Use Route Groups**: Group related routes using parentheses `(groupName)` to keep the project organized without affecting the URL. -- **Private Folders**: Use an underscore `_folderName` to prevent a folder from becoming a route segment. This is useful for storing private components or utilities. +- **Colocate Components**: Place route-specific components, such as a + ``, in the same directory as the `page.tsx` file. +- **Use Route Groups**: Group related routes using parentheses `(groupName)` to + keep the project organized without affecting the URL. +- **Private Folders**: Use an underscore `_folderName` to prevent a folder from + becoming a route segment. This is useful for storing private components or + utilities. diff --git a/nextjs/.gemini-guidelines/overview.md b/nextjs/.gemini-guidelines/overview.md index 7910580..ce5506f 100644 --- a/nextjs/.gemini-guidelines/overview.md +++ b/nextjs/.gemini-guidelines/overview.md @@ -1,32 +1,43 @@ - # Next.js Project Instructions -As an AI assistant, your primary goal is to help me build and maintain this Next.js application by following these core principles. +As an AI assistant, your primary goal is to help me build and maintain this +Next.js application by following these core principles. ## ๐Ÿ“œ **Guiding Principles** -1. **App Router First**: Prioritize the App Router for all new features. Use Route Handlers for API endpoints. The Pages Router may only be used for existing legacy code. -2. **Server Components by Default**: Embrace React Server Components (RSCs) as the default for UI. Only use Client Components (`"use client"`) when interactivity is essential. -3. **Performance is Key**: Optimize for performance by default. Use `next/image` for images, `next/font` for fonts, and leverage static generation (`generateStaticParams`) wherever possible. -4. **TypeScript Everywhere**: All new code, from components to API routes, must be written in TypeScript. -5. **Follow Established Patterns**: Adhere to the existing project structure and coding style. When in doubt, ask for clarification. +1. **App Router First**: Prioritize the App Router for all new features. Use + Route Handlers for API endpoints. The Pages Router may only be used for + existing legacy code. +2. **Server Components by Default**: Embrace React Server Components (RSCs) as + the default for UI. Only use Client Components (`"use client"`) when + interactivity is essential. +3. **Performance is Key**: Optimize for performance by default. Use + `next/image` for images, `next/font` for fonts, and leverage static + generation (`generateStaticParams`) wherever possible. +4. **TypeScript Everywhere**: All new code, from components to API routes, must + be written in TypeScript. +5. **Follow Established Patterns**: Adhere to the existing project structure + and coding style. When in doubt, ask for clarification. ## ๐Ÿ—‚๏ธ **Directory Structure** -- `/app`: Main application code using the App Router. - - `/(routes)`: Route groups for organization. - - `/api`: API routes (Route Handlers). - - `/components`: Shared UI components. - - `/lib`: Utility functions and shared logic. -- `/public`: Static assets. -- `/tests`: Testing files. +- `/app`: Main application code using the App Router. + - `/(routes)`: Route groups for organization. + - `/api`: API routes (Route Handlers). + - `/components`: Shared UI components. + - `/lib`: Utility functions and shared logic. +- `/public`: Static assets. +- `/tests`: Testing files. ## โœ… **Your Tasks** -- **Component Generation**: Create components that are modular, reusable, and follow the RSC-first approach. -- **Route Creation**: Set up new routes and API endpoints using the App Router. +- **Component Generation**: Create components that are modular, reusable, and + follow the RSC-first approach. +- **Route Creation**: Set up new routes and API endpoints using the App Router. - -- **State Management**: Use React context or `zustand` for simple state needs. Avoid prop-drilling. -- **Styling**: Use Tailwind CSS for all styling. +- **State Management**: Use React context or `zustand` for simple state needs. + Avoid prop-drilling. +- **Styling**: Use Tailwind CSS for all styling. -By following these instructions, you will help create a scalable, performant, and maintainable Next.js application. +By following these instructions, you will help create a scalable, performant, +and maintainable Next.js application. diff --git a/nextjs/.gemini-guidelines/seo-best-practices.md b/nextjs/.gemini-guidelines/seo-best-practices.md index 8008376..6f35eeb 100644 --- a/nextjs/.gemini-guidelines/seo-best-practices.md +++ b/nextjs/.gemini-guidelines/seo-best-practices.md @@ -1,11 +1,12 @@ - # SEO Best Practices Follow these guidelines to ensure all pages are optimized for search engines. ## โœ… **Instructions** -1. **Metadata API**: Use the built-in Metadata API to manage `title` and `description` for each page. Define a `metadata` object in `layout.tsx` or `page.tsx`. +1. **Metadata API**: Use the built-in Metadata API to manage `title` and + `description` for each page. Define a `metadata` object in `layout.tsx` or + `page.tsx`. ```typescript // /app/products/[id]/page.tsx @@ -21,7 +22,8 @@ Follow these guidelines to ensure all pages are optimized for search engines. } ``` -2. **Dynamic Metadata**: For dynamic pages, use the `generateMetadata` function to fetch data and create metadata. +2. **Dynamic Metadata**: For dynamic pages, use the `generateMetadata` function + to fetch data and create metadata. ```typescript // /app/products/[id]/page.tsx @@ -31,7 +33,9 @@ Follow these guidelines to ensure all pages are optimized for search engines. params: { id: string }; }; - export async function generateMetadata({ params }: Props): Promise { + export async function generateMetadata({ + params, + }: Props): Promise { const product = await getProduct(params.id); return { title: product.name, @@ -40,7 +44,8 @@ Follow these guidelines to ensure all pages are optimized for search engines. } ``` -3. **Open Graph & Twitter**: Include Open Graph and Twitter metadata to improve social sharing. +3. **Open Graph & Twitter**: Include Open Graph and Twitter metadata to improve + social sharing. ```typescript export const metadata: Metadata = { @@ -56,4 +61,5 @@ Follow these guidelines to ensure all pages are optimized for search engines. }; ``` -4. **`sitemap.ts`**: Create a `sitemap.ts` file in the `/app` directory to automatically generate a `sitemap.xml` file. +4. **`sitemap.ts`**: Create a `sitemap.ts` file in the `/app` directory to + automatically generate a `sitemap.xml` file. diff --git a/nextjs/.gemini-guidelines/testing.md b/nextjs/.gemini-guidelines/testing.md index b1582fb..254cfce 100644 --- a/nextjs/.gemini-guidelines/testing.md +++ b/nextjs/.gemini-guidelines/testing.md @@ -1,19 +1,20 @@ - # Testing Strategy Follow this testing strategy to ensure the application is reliable and bug-free. ## ๐Ÿงช **Tools** -- **Jest**: For unit testing. -- **React Testing Library**: For testing components. -- **Cypress**: For end-to-end testing. +- **Jest**: For unit testing. +- **React Testing Library**: For testing components. +- **Cypress**: For end-to-end testing. ## โœ… **Instructions** -1. **Unit Tests**: Write unit tests for individual functions and utilities in the `/lib` directory. Keep them short, focused, and fast. +1. **Unit Tests**: Write unit tests for individual functions and utilities in + the `/lib` directory. Keep them short, focused, and fast. -2. **Component Tests**: Test React components in isolation. Use React Testing Library to simulate user interactions and verify the component's behavior. +2. **Component Tests**: Test React components in isolation. Use React Testing + Library to simulate user interactions and verify the component's behavior. ```typescript // /components/Button.test.tsx @@ -26,7 +27,8 @@ Follow this testing strategy to ensure the application is reliable and bug-free. }); ``` -3. **End-to-End (E2E) Tests**: Use Cypress to test critical user flows from start to finish. For example, a full sign-up or checkout process. +3. **End-to-End (E2E) Tests**: Use Cypress to test critical user flows from + start to finish. For example, a full sign-up or checkout process. ```javascript // /cypress/e2e/auth.cy.js @@ -39,4 +41,6 @@ Follow this testing strategy to ensure the application is reliable and bug-free. }); ``` -4. **Test Coverage**: Aim for a reasonable level of test coverage, but prioritize testing critical paths and complex logic over simple, static components. +4. **Test Coverage**: Aim for a reasonable level of test coverage, but + prioritize testing critical paths and complex logic over simple, static + components. diff --git a/nextjs/GEMINI.md b/nextjs/GEMINI.md index 1265033..756f7f0 100644 --- a/nextjs/GEMINI.md +++ b/nextjs/GEMINI.md @@ -2,33 +2,49 @@ ## Project Introduction -This project is a **TODO List Application** built to demonstrate modern web development practices. It allows users to manage their daily tasks efficiently, providing a clear and intuitive interface for adding, completing, and deleting to-do items. +This project is a **TODO List Application** built to demonstrate modern web +development practices. It allows users to manage their daily tasks efficiently, +providing a clear and intuitive interface for adding, completing, and deleting +to-do items. ## Core Features -* **Add New Todos**: Quickly add new tasks to the list. -* **Mark Todos as Complete**: Toggle the completion status of tasks. -* **Delete Todos**: Remove unwanted tasks from the list. -* **Filter Todos**: View all, active, or completed tasks. -* **Persistence**: Todos are saved and loaded (e.g., from local storage or a backend API). +- **Add New Todos**: Quickly add new tasks to the list. +- **Mark Todos as Complete**: Toggle the completion status of tasks. +- **Delete Todos**: Remove unwanted tasks from the list. +- **Filter Todos**: View all, active, or completed tasks. +- **Persistence**: Todos are saved and loaded (e.g., from local storage or a + backend API). ## Build and Deployment To set up and run this application: -1. **Install Dependencies**: Run `npm install` or `yarn install` in the project root. -2. **Run Development Server**: Execute `npm run dev` or `yarn dev` to start the development server. The application will be accessible at `http://localhost:3000`. -3. **Build for Production**: Run `npm run build` or `yarn build` to create an optimized production build. -4. **Start Production Server**: Execute `npm run start` or `yarn start` to serve the production build. +1. **Install Dependencies**: Run `npm install` or `yarn install` in the project + root. +2. **Run Development Server**: Execute `npm run dev` or `yarn dev` to start the + development server. The application will be accessible at + `http://localhost:3000`. +3. **Build for Production**: Run `npm run build` or `yarn build` to create an + optimized production build. +4. **Start Production Server**: Execute `npm run start` or `yarn start` to + serve the production build. --- -This project is a **Next.js** application, built with React and focusing on server-side rendering, static site generation, and API routes. It emphasizes performance, SEO, and a great developer experience. - -## Key Instructions & Guidelines: - -* **General Instructions**: See `.gemini-guidelines/overview.md` for core principles and tasks. -* **App Router Structure**: See `.gemini-guidelines/app-router-structure.md` for organizing your Next.js application with the App Router. -* **API Routes**: See `.gemini-guidelines/api-routes.md` for guidelines on creating and using API routes. -* **SEO Best Practices**: See `.gemini-guidelines/seo-best-practices.md` for optimizing your Next.js application for search engines. -* **Testing Strategy**: See `.gemini-guidelines/testing.md` for testing guidelines. +This project is a **Next.js** application, built with React and focusing on +server-side rendering, static site generation, and API routes. It emphasizes +performance, SEO, and a great developer experience. + +## Key Instructions & Guidelines + +- **General Instructions**: See `.gemini-guidelines/overview.md` for core + principles and tasks. +- **App Router Structure**: See `.gemini-guidelines/app-router-structure.md` for + organizing your Next.js application with the App Router. +- **API Routes**: See `.gemini-guidelines/api-routes.md` for guidelines on + creating and using API routes. +- **SEO Best Practices**: See `.gemini-guidelines/seo-best-practices.md` for + optimizing your Next.js application for search engines. +- **Testing Strategy**: See `.gemini-guidelines/testing.md` for testing + guidelines. diff --git a/node/.gemini-guidelines/async-patterns.md b/node/.gemini-guidelines/async-patterns.md index daad39c..c20af87 100644 --- a/node/.gemini-guidelines/async-patterns.md +++ b/node/.gemini-guidelines/async-patterns.md @@ -1,11 +1,11 @@ - # Asynchronous Programming Follow these best practices for writing clean and efficient asynchronous code. ## โœ… **Instructions** -1. **Use `async/await`**: Always prefer `async/await` over callbacks or `.then()` chains for better readability and error handling. +1. **Use `async/await`**: Always prefer `async/await` over callbacks or + `.then()` chains for better readability and error handling. ```javascript // Good @@ -21,16 +21,17 @@ Follow these best practices for writing clean and efficient asynchronous code. // Bad function fetchData() { someAsyncOperation() - .then(data => { + .then((data) => { return data; }) - .catch(error => { + .catch((error) => { console.error(error); }); } ``` -2. **Parallel Execution**: When you need to run multiple asynchronous operations concurrently, use `Promise.all`. +2. **Parallel Execution**: When you need to run multiple asynchronous + operations concurrently, use `Promise.all`. ```javascript async function getParallelData() { @@ -42,4 +43,5 @@ Follow these best practices for writing clean and efficient asynchronous code. } ``` -3. **Avoid Mixing Styles**: Do not mix `async/await` with `.then()` in the same function. Be consistent. +3. **Avoid Mixing Styles**: Do not mix `async/await` with `.then()` in the same + function. Be consistent. diff --git a/node/.gemini-guidelines/error-handling.md b/node/.gemini-guidelines/error-handling.md index 2ebbd60..21a1b83 100644 --- a/node/.gemini-guidelines/error-handling.md +++ b/node/.gemini-guidelines/error-handling.md @@ -1,11 +1,12 @@ - # Error Handling Follow these guidelines for consistent and effective error handling. ## โœ… **Instructions** -1. **Centralized Error Middleware**: Use a single, centralized error-handling middleware in your Express application. This should be the last middleware added. +1. **Centralized Error Middleware**: Use a single, centralized error-handling + middleware in your Express application. This should be the last middleware + added. ```javascript // server.js @@ -14,7 +15,8 @@ Follow these guidelines for consistent and effective error handling. app.use(errorHandler); ``` -2. **Custom Error Class**: Create a custom `AppError` class to standardize operational errors. +2. **Custom Error Class**: Create a custom `AppError` class to standardize + operational errors. ```javascript // utils/AppError.js @@ -30,7 +32,8 @@ Follow these guidelines for consistent and effective error handling. module.exports = AppError; ``` -3. **Catching Async Errors**: Wrap your async route handlers in a `catchAsync` utility to avoid repetitive `try...catch` blocks. +3. **Catching Async Errors**: Wrap your async route handlers in a `catchAsync` + utility to avoid repetitive `try...catch` blocks. ```javascript // utils/catchAsync.js diff --git a/node/.gemini-guidelines/overview.md b/node/.gemini-guidelines/overview.md index 280e3bf..88c06fd 100644 --- a/node/.gemini-guidelines/overview.md +++ b/node/.gemini-guidelines/overview.md @@ -1,33 +1,42 @@ - # Node.js Project Instructions -As an AI assistant, your role is to help build and maintain this Node.js application by adhering to the following principles. +As an AI assistant, your role is to help build and maintain this Node.js +application by adhering to the following principles. ## ๐Ÿ“œ **Guiding Principles** -1. **Asynchronous by Default**: Use `async/await` for all asynchronous operations. Avoid callbacks and raw Promises where possible. -2. **Modular Structure**: Keep the codebase modular. Separate concerns into different files and directories (e.g., `routes`, `controllers`, `services`). -3. **Error Handling is Crucial**: Implement robust error handling for all API routes and services. Use a centralized error-handling middleware. -4. **Security First**: Follow security best practices to protect against common vulnerabilities (e.g., XSS, SQL injection). -5. **Use Environment Variables**: Store all configuration and secrets in environment variables. Never hard-code them. +1. **Asynchronous by Default**: Use `async/await` for all asynchronous + operations. Avoid callbacks and raw Promises where possible. +2. **Modular Structure**: Keep the codebase modular. Separate concerns into + different files and directories (e.g., `routes`, `controllers`, `services`). +3. **Error Handling is Crucial**: Implement robust error handling for all API + routes and services. Use a centralized error-handling middleware. +4. **Security First**: Follow security best practices to protect against common + vulnerabilities (e.g., XSS, SQL injection). +5. **Use Environment Variables**: Store all configuration and secrets in + environment variables. Never hard-code them. ## ๐Ÿ—‚๏ธ **Directory Structure** -- `/src`: Main application code. - - `/api`: API routes. - - `/config`: Configuration files. - - `/controllers`: Route handlers. - - `/middleware`: Custom middleware. - - `/models`: Database models. - - `/services`: Business logic. - - `/utils`: Utility functions. -- `/tests`: Testing files. +- `/src`: Main application code. + - `/api`: API routes. + - `/config`: Configuration files. + - `/controllers`: Route handlers. + - `/middleware`: Custom middleware. + - `/models`: Database models. + - `/services`: Business logic. + - `/utils`: Utility functions. +- `/tests`: Testing files. ## โœ… **Your Tasks** -- **API Endpoint Creation**: Build RESTful API endpoints that are clean, well-structured, and follow the defined patterns. -- **Database Interaction**: Write efficient and secure database queries. -- **Middleware Implementation**: Create middleware for tasks like authentication, validation, and logging. -- **Code Refactoring**: Improve existing code by making it more modular, performant, and readable. +- **API Endpoint Creation**: Build RESTful API endpoints that are clean, + well-structured, and follow the defined patterns. +- **Database Interaction**: Write efficient and secure database queries. +- **Middleware Implementation**: Create middleware for tasks like + authentication, validation, and logging. +- **Code Refactoring**: Improve existing code by making it more modular, + performant, and readable. -By following these instructions, you will help create a robust, secure, and scalable Node.js application. +By following these instructions, you will help create a robust, secure, and +scalable Node.js application. diff --git a/node/.gemini-guidelines/security.md b/node/.gemini-guidelines/security.md index 9363015..363b70f 100644 --- a/node/.gemini-guidelines/security.md +++ b/node/.gemini-guidelines/security.md @@ -1,22 +1,26 @@ - # Security Best Practices Follow these guidelines to secure the Node.js application. ## โœ… **Instructions** -1. **Use Helmet**: Use the `helmet` middleware to set various HTTP headers that help protect against common attacks. +1. **Use Helmet**: Use the `helmet` middleware to set various HTTP headers that + help protect against common attacks. ```javascript const helmet = require('helmet'); app.use(helmet()); ``` -2. **Prevent SQL Injection**: Use an ORM (like Sequelize or Mongoose) or parameterized queries to prevent SQL injection attacks. Never use string concatenation to build queries. +2. **Prevent SQL Injection**: Use an ORM (like Sequelize or Mongoose) or + parameterized queries to prevent SQL injection attacks. Never use string + concatenation to build queries. -3. **Prevent XSS**: Sanitize user input to prevent Cross-Site Scripting (XSS) attacks. Use a library like `dompurify`. +3. **Prevent XSS**: Sanitize user input to prevent Cross-Site Scripting (XSS) + attacks. Use a library like `dompurify`. -4. **Rate Limiting**: Implement rate limiting to protect against brute-force attacks. +4. **Rate Limiting**: Implement rate limiting to protect against brute-force + attacks. ```javascript const rateLimit = require('express-rate-limit'); @@ -29,4 +33,5 @@ Follow these guidelines to secure the Node.js application. app.use('/api', limiter); ``` -5. **Secure Dependencies**: Regularly audit your dependencies for known vulnerabilities using `npm audit`. +5. **Secure Dependencies**: Regularly audit your dependencies for known + vulnerabilities using `npm audit`. diff --git a/node/GEMINI.md b/node/GEMINI.md index ca1367d..54563d5 100644 --- a/node/GEMINI.md +++ b/node/GEMINI.md @@ -2,32 +2,47 @@ ## Project Introduction -This project is a **TODO List Application** built to demonstrate modern web development practices. It allows users to manage their daily tasks efficiently, providing a clear and intuitive interface for adding, completing, and deleting to-do items. +This project is a **TODO List Application** built to demonstrate modern web +development practices. It allows users to manage their daily tasks efficiently, +providing a clear and intuitive interface for adding, completing, and deleting +to-do items. ## Core Features -* **Add New Todos**: Quickly add new tasks to the list. -* **Mark Todos as Complete**: Toggle the completion status of tasks. -* **Delete Todos**: Remove unwanted tasks from the list. -* **Filter Todos**: View all, active, or completed tasks. -* **Persistence**: Todos are saved and loaded (e.g., from local storage or a backend API). +- **Add New Todos**: Quickly add new tasks to the list. +- **Mark Todos as Complete**: Toggle the completion status of tasks. +- **Delete Todos**: Remove unwanted tasks from the list. +- **Filter Todos**: View all, active, or completed tasks. +- **Persistence**: Todos are saved and loaded (e.g., from local storage or a + backend API). ## Build and Deployment To set up and run this application: -1. **Install Dependencies**: Run `npm install` or `yarn install` in the project root. -2. **Run Development Server**: Execute `npm run dev` or `yarn dev` to start the development server. The application will be accessible at `http://localhost:3000`. -3. **Build for Production**: Run `npm run build` or `yarn build` to create an optimized production build. -4. **Start Production Server**: Execute `npm run start` or `yarn start` to serve the production build. +1. **Install Dependencies**: Run `npm install` or `yarn install` in the project + root. +2. **Run Development Server**: Execute `npm run dev` or `yarn dev` to start the + development server. The application will be accessible at + `http://localhost:3000`. +3. **Build for Production**: Run `npm run build` or `yarn build` to create an + optimized production build. +4. **Start Production Server**: Execute `npm run start` or `yarn start` to + serve the production build. --- -This project is a **Node.js** backend application, likely using Express.js or a similar framework. It focuses on building robust, scalable, and secure server-side logic. +This project is a **Node.js** backend application, likely using Express.js or a +similar framework. It focuses on building robust, scalable, and secure +server-side logic. -## Key Instructions & Guidelines: +## Key Instructions & Guidelines -* **General Instructions**: See `.gemini-guidelines/overview.md` for core principles and tasks. -* **Error Handling**: See `.gemini-guidelines/error-handling.md` for consistent error management. -* **Asynchronous Patterns**: See `.gemini-guidelines/async-patterns.md` for best practices in asynchronous programming. -* **Security**: See `.gemini-guidelines/security.md` for security best practices. \ No newline at end of file +- **General Instructions**: See `.gemini-guidelines/overview.md` for core + principles and tasks. +- **Error Handling**: See `.gemini-guidelines/error-handling.md` for consistent + error management. +- **Asynchronous Patterns**: See `.gemini-guidelines/async-patterns.md` for best + practices in asynchronous programming. +- **Security**: See `.gemini-guidelines/security.md` for security best + practices. diff --git a/react/.gemini-guidelines/component-design.md b/react/.gemini-guidelines/component-design.md index 5cbfcaf..20b3c56 100644 --- a/react/.gemini-guidelines/component-design.md +++ b/react/.gemini-guidelines/component-design.md @@ -1,17 +1,22 @@ - # Component Design -Follow these principles for designing clean, reusable, and maintainable React components. +Follow these principles for designing clean, reusable, and maintainable React +components. ## โœ… **Instructions** -1. **Single Responsibility Principle**: A component should do one thing and do it well. If a component becomes too complex, break it down into smaller components. +1. **Single Responsibility Principle**: A component should do one thing and do + it well. If a component becomes too complex, break it down into smaller + components. -2. **Container vs. Presentational Components**: Separate logic (container) from UI (presentational). - - **Container Components**: Manage state and data fetching. - - **Presentational Components**: Receive data via props and render UI. They are often pure functions. +2. **Container vs. Presentational Components**: Separate logic (container) from + UI (presentational). + - **Container Components**: Manage state and data fetching. + - **Presentational Components**: Receive data via props and render UI. They + are often pure functions. -3. **Props Typing**: Use TypeScript interfaces or types to define the props for every component. +3. **Props Typing**: Use TypeScript interfaces or types to define the props for + every component. ```typescript interface ButtonProps { @@ -25,6 +30,8 @@ Follow these principles for designing clean, reusable, and maintainable React co }; ``` -4. **Composition over Inheritance**: Use composition to share code between components. Avoid component inheritance. +4. **Composition over Inheritance**: Use composition to share code between + components. Avoid component inheritance. -5. **Consistent Naming**: Name components clearly and consistently. Use PascalCase for component files and names (e.g., `UserProfile.tsx`). +5. **Consistent Naming**: Name components clearly and consistently. Use + PascalCase for component files and names (e.g., `UserProfile.tsx`). diff --git a/react/.gemini-guidelines/hooks-best-practices.md b/react/.gemini-guidelines/hooks-best-practices.md index 550f260..b4392ca 100644 --- a/react/.gemini-guidelines/hooks-best-practices.md +++ b/react/.gemini-guidelines/hooks-best-practices.md @@ -1,15 +1,18 @@ - # React Hooks Best Practices Follow these guidelines for using React Hooks effectively. ## โœ… **Instructions** -1. **Only Call Hooks at the Top Level**: Do not call Hooks inside loops, conditions, or nested functions. +1. **Only Call Hooks at the Top Level**: Do not call Hooks inside loops, + conditions, or nested functions. -2. **Only Call Hooks from React Functions**: Call Hooks from React functional components or custom Hooks. +2. **Only Call Hooks from React Functions**: Call Hooks from React functional + components or custom Hooks. -3. **Custom Hooks for Reusable Logic**: Extract component logic into reusable custom Hooks. Name custom Hooks with the `use` prefix (e.g., `useFetchData`). +3. **Custom Hooks for Reusable Logic**: Extract component logic into reusable + custom Hooks. Name custom Hooks with the `use` prefix (e.g., + `useFetchData`). ```typescript // hooks/useFetchData.ts @@ -27,6 +30,10 @@ Follow these guidelines for using React Hooks effectively. } ``` -4. **`useEffect` Dependencies**: Be mindful of the dependency array in `useEffect`. Include all values that the effect depends on. An empty array `[]` means the effect runs only once. +4. **`useEffect` Dependencies**: Be mindful of the dependency array in + `useEffect`. Include all values that the effect depends on. An empty array + `[]` means the effect runs only once. -5. **Use `useCallback` and `useMemo` for Optimization**: Use `useCallback` to memoize functions and `useMemo` to memoize values to prevent unnecessary re-renders, but don't overuse them. +5. **Use `useCallback` and `useMemo` for Optimization**: Use `useCallback` to + memoize functions and `useMemo` to memoize values to prevent unnecessary + re-renders, but don't overuse them. diff --git a/react/.gemini-guidelines/overview.md b/react/.gemini-guidelines/overview.md index 95554e0..4ed8a13 100644 --- a/react/.gemini-guidelines/overview.md +++ b/react/.gemini-guidelines/overview.md @@ -1,34 +1,44 @@ - # React Project Instructions -As an AI assistant, your primary goal is to help me build and maintain this React application by following these core principles. +As an AI assistant, your primary goal is to help me build and maintain this +React application by following these core principles. ## ๐Ÿ“œ **Guiding Principles** -1. **Functional Components and Hooks**: All new components must be functional components using React Hooks. Class components are considered legacy. -2. **Component-Based Architecture**: Build small, reusable components. Follow the Single Responsibility Principle for each component. -3. **TypeScript is Standard**: All new code, including components and utility functions, must be written in TypeScript. -4. **Follow Design Patterns**: Adhere to established patterns for component design, state management, and styling. -5. **Accessibility Matters**: Ensure all components are accessible and follow ARIA standards. +1. **Functional Components and Hooks**: All new components must be functional + components using React Hooks. Class components are considered legacy. +2. **Component-Based Architecture**: Build small, reusable components. Follow + the Single Responsibility Principle for each component. +3. **TypeScript is Standard**: All new code, including components and utility + functions, must be written in TypeScript. +4. **Follow Design Patterns**: Adhere to established patterns for component + design, state management, and styling. +5. **Accessibility Matters**: Ensure all components are accessible and follow + ARIA standards. ## ๐Ÿ—‚๏ธ **Directory Structure** -- `/src`: Main application code. - - `/components`: Reusable UI components. - - `/common`: Basic, generic components (Button, Input, etc.). - - `/layout`: Layout components (Header, Footer, etc.). - - `/feature`: Components specific to a feature. - - `/hooks`: Custom hooks. - - `/pages` or `/views`: Top-level page components. - - `/store` or `/context`: State management files. - - `/utils`: Utility functions. -- `/tests`: Testing files. +- `/src`: Main application code. + - `/components`: Reusable UI components. + - `/common`: Basic, generic components (Button, Input, etc.). + - `/layout`: Layout components (Header, Footer, etc.). + - `/feature`: Components specific to a feature. + - `/hooks`: Custom hooks. + - `/pages` or `/views`: Top-level page components. + - `/store` or `/context`: State management files. + - `/utils`: Utility functions. +- `/tests`: Testing files. ## โœ… **Your Tasks** -- **Component Creation**: Generate modular, well-typed, and accessible React components. -- **State Management**: Implement state solutions using React Context, Zustand, or Redux Toolkit, depending on the complexity. -- **Styling**: Use the project's designated styling solution (e.g., Tailwind CSS, Styled Components). -- **Refactoring**: Improve existing components by making them more reusable, performant, and readable. - -By following these instructions, you will help create a high-quality, maintainable, and scalable React application. +- **Component Creation**: Generate modular, well-typed, and accessible React + components. +- **State Management**: Implement state solutions using React Context, Zustand, + or Redux Toolkit, depending on the complexity. +- **Styling**: Use the project's designated styling solution (e.g., Tailwind + CSS, Styled Components). +- **Refactoring**: Improve existing components by making them more reusable, + performant, and readable. + +By following these instructions, you will help create a high-quality, +maintainable, and scalable React application. diff --git a/react/.gemini-guidelines/state-management.md b/react/.gemini-guidelines/state-management.md index 895670b..a64c21e 100644 --- a/react/.gemini-guidelines/state-management.md +++ b/react/.gemini-guidelines/state-management.md @@ -1,13 +1,15 @@ - # State Management Choose the right state management tool for the job. ## โœ… **Instructions** -1. **Local State (`useState`)**: For state that is local to a single component, always use the `useState` Hook. +1. **Local State (`useState`)**: For state that is local to a single component, + always use the `useState` Hook. -2. **Shared State (`React Context`)**: For state that needs to be shared between a few components, use React Context with the `useContext` Hook. This is suitable for simple to moderately complex state. +2. **Shared State (`React Context`)**: For state that needs to be shared + between a few components, use React Context with the `useContext` Hook. This + is suitable for simple to moderately complex state. ```typescript // context/AuthContext.tsx @@ -24,8 +26,12 @@ Choose the right state management tool for the job. export const useAuth = () => useContext(AuthContext); ``` -3. **Complex Global State (`Zustand` or `Redux Toolkit`)**: For complex, application-wide state, use a dedicated state management library. - - **Zustand**: A lightweight, simple, and unopinionated choice. - - **Redux Toolkit**: A more structured and powerful option for large-scale applications. +3. **Complex Global State (`Zustand` or `Redux Toolkit`)**: For complex, + application-wide state, use a dedicated state management library. + - **Zustand**: A lightweight, simple, and unopinionated choice. + - **Redux Toolkit**: A more structured and powerful option for large-scale + applications. -4. **Server State (`React Query` or `SWR`)**: For managing server state (data fetching, caching, etc.), use a library like React Query or SWR. Do not store server state in your global client-side store. +4. **Server State (`React Query` or `SWR`)**: For managing server state (data + fetching, caching, etc.), use a library like React Query or SWR. Do not + store server state in your global client-side store. diff --git a/react/.gemini-guidelines/testing.md b/react/.gemini-guidelines/testing.md index 09db7a7..8ec904c 100644 --- a/react/.gemini-guidelines/testing.md +++ b/react/.gemini-guidelines/testing.md @@ -1,19 +1,19 @@ - # Testing Strategy Follow this testing strategy to ensure the application is reliable and bug-free. ## ๐Ÿงช **Tools** -- **Jest**: For unit testing. -- **React Testing Library**: For testing components. -- **Cypress**: For end-to-end testing. +- **Jest**: For unit testing. +- **React Testing Library**: For testing components. +- **Cypress**: For end-to-end testing. ## โœ… **Instructions** 1. **Unit Tests**: Write unit tests for custom Hooks and utility functions. -2. **Component Tests**: Test React components from the user's perspective. Use React Testing Library to find elements and interact with them. +2. **Component Tests**: Test React components from the user's perspective. Use + React Testing Library to find elements and interact with them. ```typescript // components/UserProfile.test.tsx @@ -27,6 +27,8 @@ Follow this testing strategy to ensure the application is reliable and bug-free. }); ``` -3. **Integration Tests**: Test how multiple components work together. For example, test a form component with its input and button components. +3. **Integration Tests**: Test how multiple components work together. For + example, test a form component with its input and button components. -4. **End-to-End (E2E) Tests**: Use Cypress to test critical user flows across the entire application. +4. **End-to-End (E2E) Tests**: Use Cypress to test critical user flows across + the entire application. diff --git a/react/GEMINI.md b/react/GEMINI.md index 8a9fa74..df6f198 100644 --- a/react/GEMINI.md +++ b/react/GEMINI.md @@ -2,33 +2,49 @@ ## Project Introduction -This project is a **TODO List Application** built to demonstrate modern web development practices. It allows users to manage their daily tasks efficiently, providing a clear and intuitive interface for adding, completing, and deleting to-do items. +This project is a **TODO List Application** built to demonstrate modern web +development practices. It allows users to manage their daily tasks efficiently, +providing a clear and intuitive interface for adding, completing, and deleting +to-do items. ## Core Features -* **Add New Todos**: Quickly add new tasks to the list. -* **Mark Todos as Complete**: Toggle the completion status of tasks. -* **Delete Todos**: Remove unwanted tasks from the list. -* **Filter Todos**: View all, active, or completed tasks. -* **Persistence**: Todos are saved and loaded (e.g., from local storage or a backend API). +- **Add New Todos**: Quickly add new tasks to the list. +- **Mark Todos as Complete**: Toggle the completion status of tasks. +- **Delete Todos**: Remove unwanted tasks from the list. +- **Filter Todos**: View all, active, or completed tasks. +- **Persistence**: Todos are saved and loaded (e.g., from local storage or a + backend API). ## Build and Deployment To set up and run this application: -1. **Install Dependencies**: Run `npm install` or `yarn install` in the project root. -2. **Run Development Server**: Execute `npm run dev` or `yarn dev` to start the development server. The application will be accessible at `http://localhost:3000`. -3. **Build for Production**: Run `npm run build` or `yarn build` to create an optimized production build. -4. **Start Production Server**: Execute `npm run start` or `yarn start` to serve the production build. +1. **Install Dependencies**: Run `npm install` or `yarn install` in the project + root. +2. **Run Development Server**: Execute `npm run dev` or `yarn dev` to start the + development server. The application will be accessible at + `http://localhost:3000`. +3. **Build for Production**: Run `npm run build` or `yarn build` to create an + optimized production build. +4. **Start Production Server**: Execute `npm run start` or `yarn start` to + serve the production build. --- -This project is a **React** frontend application, built with functional components and React Hooks. It emphasizes modularity, reusability, and type safety with TypeScript. - -## Key Instructions & Guidelines: - -* **General Instructions**: See `.gemini-guidelines/overview.md` for core principles and tasks. -* **Component Design**: See `.gemini-guidelines/component-design.md` for principles on building clean React components. -* **Hooks Best Practices**: See `.gemini-guidelines/hooks-best-practices.md` for effective use of React Hooks. -* **State Management**: See `.gemini-guidelines/state-management.md` for guidelines on managing application state. -* **Testing Strategy**: See `.gemini-guidelines/testing.md` for testing guidelines. \ No newline at end of file +This project is a **React** frontend application, built with functional +components and React Hooks. It emphasizes modularity, reusability, and type +safety with TypeScript. + +## Key Instructions & Guidelines + +- **General Instructions**: See `.gemini-guidelines/overview.md` for core + principles and tasks. +- **Component Design**: See `.gemini-guidelines/component-design.md` for + principles on building clean React components. +- **Hooks Best Practices**: See `.gemini-guidelines/hooks-best-practices.md` for + effective use of React Hooks. +- **State Management**: See `.gemini-guidelines/state-management.md` for + guidelines on managing application state. +- **Testing Strategy**: See `.gemini-guidelines/testing.md` for testing + guidelines. diff --git a/rule.json b/rule.json new file mode 100644 index 0000000..1edf8c3 --- /dev/null +++ b/rule.json @@ -0,0 +1,63 @@ +{ + "name": "Main Branch Protection - Code Instructions Kit", + "target": "branch", + "enforcement": "active", + "conditions": { + "ref_name": { + "include": [ + "~DEFAULT_BRANCH" + ] + } + }, + "rules": [ + { + "type": "pull_request", + "parameters": { + "required_approving_review_count": 1, + "dismiss_stale_reviews_on_push": true, + "require_last_push_approval": false, + "required_review_thread_resolution": true + } + }, + { + "type": "required_status_checks", + "parameters": { + "required_status_checks": [ + { + "context": "Markdown Lint" + } + ], + "strict_required_status_checks_policy": true + } + }, + { + "type": "non_fast_forward" + }, + { + "type": "deletion" + }, + { + "type": "commit_message_pattern", + "parameters": { + "name": "Conventional Commits", + "pattern": "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\\(.+\\))?:\\s.{1,50}", + "negate": false + } + }, + { + "type": "commit_author_email_pattern", + "parameters": { + "name": "Valid Author Email", + "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$", + "negate": false + } + } + ], + "bypasses": [ + { + "actor_id": 1, + "actor_type": "RepositoryRole", + "bypass_mode": "always" + } + ] +} \ No newline at end of file diff --git a/shared-guidelines/accessibility.md b/shared-guidelines/accessibility.md index 1f5e815..697b37f 100644 --- a/shared-guidelines/accessibility.md +++ b/shared-guidelines/accessibility.md @@ -1,46 +1,65 @@ # Accessibility Instructions โ™ฟ๏ธ -As an AI assistant, your most important task is to build web applications that are usable by everyone, including people with disabilities. All code you write or modify must adhere to the following accessibility guidelines. +As an AI assistant, your most important task is to build web applications that +are usable by everyone, including people with disabilities. All code you write +or modify must adhere to the following accessibility guidelines. --- ## โœ… **Core Instructions for AI** -When generating or refactoring any component, page, or code snippet, you **MUST** ensure the following: +When generating or refactoring any component, page, or code snippet, you +**MUST** ensure the following: 1. **Use Semantic HTML**: - * Always default to native HTML elements (`