diff --git a/.github/custom-issue-template/frontend-kit/0. Generate project and establish integration point.md b/.github/custom-issue-template/frontend-kit/0. Generate project and establish integration point.md index 9ee072ec3..d28b2deb5 100644 --- a/.github/custom-issue-template/frontend-kit/0. Generate project and establish integration point.md +++ b/.github/custom-issue-template/frontend-kit/0. Generate project and establish integration point.md @@ -1,7 +1,9 @@ # Background + To make tasks parallelizable, we should create kits via integration branches to make PRs smaller and easier to read while not breaking the upstream build. Integration branches may be cleaner and easier to implement in isolation as kits are isolated to their own directory anyway. # Acceptance + - [ ] Generate new project in the `starters/` creating a name that includes 'framework-store-style' format - [ ] Find the title in the `` of the public facing index.html (this depends from framework, but usually found in "src/public" folder) and change it to "framework-store-style starter kit" - [ ] Change the name and description in the package.json diff --git a/.github/custom-issue-template/frontend-kit/1. Add linting and prettier configurations.md b/.github/custom-issue-template/frontend-kit/1. Add linting and prettier configurations.md index 9a4ba8f53..128d13c05 100644 --- a/.github/custom-issue-template/frontend-kit/1. Add linting and prettier configurations.md +++ b/.github/custom-issue-template/frontend-kit/1. Add linting and prettier configurations.md @@ -1,11 +1,15 @@ # Background + Having code style consistency is important for any project. A standardized set of options should be set that can be overwritten by the implementer at a later date. # Acceptance -- [ ] Establish eslint/tslint rules and configuration -- [ ] Install and configure prettier -- [ ] Configure editorconfig settings + +- [ ] Establish eslint/tslint rules and configuration. Code formatting should be enforced via ESLint rules. Rules should be set to the strictest setting and enforced via CI. The standard rules for a stack should be selected and if there are specialized plugins, those should be utilized and appropriately tuned. +- [ ] Install and configure prettier. Prettier should be configured to save on format and align with the established ESLint rules. +- [ ] Configure editorconfig settings. Most editors support the EditorConfig syntax. Setting the project’s editor settings to align with the selected ESLint & Prettier rules should be established for code conformity and to improve the developer experience. +- [ ] Tabs: It has been proven that tabs are better than spaces for accessibility purposes. As such, all tooling should be configured to use tabs when possible. YAML is a known exception. - [ ] Run linting and prettier on entire project and correct any errors # NOTE: -This task has already been completed many times on different KITs, so we should make sure to look at those configurations first and try not to reinvent the wheel :) \ No newline at end of file + +This task has already been completed many times on different KITs, so we should make sure to look at those configurations first and try not to reinvent the wheel :) diff --git a/.github/custom-issue-template/frontend-kit/1. Add store to the project.md b/.github/custom-issue-template/frontend-kit/1. Add store to the project.md index f0334d149..cf3396ff8 100644 --- a/.github/custom-issue-template/frontend-kit/1. Add store to the project.md +++ b/.github/custom-issue-template/frontend-kit/1. Add store to the project.md @@ -1,8 +1,9 @@ # Background -Each kit should have a provided state manager setup and be configured for usage. +Each kit should have a provided state manager setup and be configured for usage. Most frontend applications require some level of state management. This can be done in several ways pending the implementation. Redux is a great example of a global store that manages UI state and its relation to server data. React Query and Apollo Client are good tools for managing server state. Sometimes a page’s route in conjunction with a metaframework router is sufficient to maintain a page’s state. Whatever the decision, we should provide a configured set of a tooling a consumer can use out of the box. # Acceptance -- [ ] Add the chosen state management into the Kit -- [ ] make sure the store works succesfully \ No newline at end of file +- [ ] All solutions require some level of application-level configuration or a sample store. This should be included as part of the kit. +- [ ] Test that the store works succesfully. +- [ ] There is a detailed explanation in the kit’s README. diff --git a/.github/custom-issue-template/frontend-kit/1. Add the styles configuration to the kit.md b/.github/custom-issue-template/frontend-kit/1. Add the styles configuration to the kit.md index efb75d7f2..bf052d4d5 100644 --- a/.github/custom-issue-template/frontend-kit/1. Add the styles configuration to the kit.md +++ b/.github/custom-issue-template/frontend-kit/1. Add the styles configuration to the kit.md @@ -1,6 +1,8 @@ # Background -Each kit should have a styling setup and be configured for usage. + +Most modern frameworks don’t use standard CSS and opt for solutions that make writing styles easier whether it be a preprocessor language, component library, or utility framework. Our job is to define those standards. Each kit should have a styling setup and be configured for usage. # Acceptance -- [ ] Add and configure the style methodology choosen for this KIT -- [ ] Make sure the style work both in Dev and Production mode \ No newline at end of file + +- [ ] All solutions require some level of application-level configuration. This should be included as part of the kit. Add and configure the style methodology choosen for this KIT. +- [ ] Whatever solution you choose, ensure there is a detailed explanation of intended use and expansion in the kit’s README. Make sure the style work both in Dev and Production mode. diff --git a/.github/custom-issue-template/frontend-kit/2. Add routing and create homepage.md b/.github/custom-issue-template/frontend-kit/2. Add routing and create homepage.md index 4e5055af7..f2c688c6a 100644 --- a/.github/custom-issue-template/frontend-kit/2. Add routing and create homepage.md +++ b/.github/custom-issue-template/frontend-kit/2. Add routing and create homepage.md @@ -1,14 +1,19 @@ # Background -We want to demonstrate basic routing as part of each kit. To do so, we want a homepage that directs to all the examples we've created thus far. + +Whether this is a kit for a SPA or MPA, routing will be a factor. We should provide a standard way for defining and implementing routes. We want to demonstrate basic routing as part of each kit. To do so, we want a homepage that directs to all the examples we've created thus far. # Acceptance -- [ ] Add and configure routing + +- [ ] All solutions require some level of application-level configuration. - [ ] Create a basic homepage that lives at `/` - [ ] Route the counter component to `/counter` - [ ] Route the API component to `/api-example` +- [ ] Ensure there is a detailed explanation of intended use and expansion in the kit’s README. # Note: + - The mock was taken from a different kit. Change the text to be align with the current kit # Mock + ![image](https://user-images.githubusercontent.com/1815379/161788828-1927cca6-f917-41f4-a971-e6bc92bb4818.png) diff --git a/.github/custom-issue-template/frontend-kit/2. Add testing to the current Kit.md b/.github/custom-issue-template/frontend-kit/2. Add testing to the current Kit.md index dfcb7e0c7..614ecdb2b 100644 --- a/.github/custom-issue-template/frontend-kit/2. Add testing to the current Kit.md +++ b/.github/custom-issue-template/frontend-kit/2. Add testing to the current Kit.md @@ -1,8 +1,9 @@ # Background -Each kit should have a provided a unit testing framework fully installed and configured to be used. +Component testing is an important out-of-the-box feature for kits. We should provide a configured testing toolchain. Jest & Vitest are currently the most popular but Cypress Component Testing is an option as well. We should also provide popular and commonly used extensions such as testing-library to help with accessibility testing. Each kit should have a provided a unit testing framework fully installed and configured to be used. # Acceptance -- [ ] Add the chosen testing framework -- [ ] When I run yarn test, I should see the tests pass on a simple `expect(true).toBe(true)` test. \ No newline at end of file +- [ ] Add the chosen testing framework. +- [ ] When I run `yarn test`, I should see the tests pass on a simple `expect(true).toBe(true)` test. +- [ ] Ensure there is a detailed explanation of intended use and expansion in the kit’s README. diff --git a/.github/custom-issue-template/frontend-kit/2. Setup Storybook.md b/.github/custom-issue-template/frontend-kit/2. Setup Storybook.md index f5ac8c769..559fdd774 100644 --- a/.github/custom-issue-template/frontend-kit/2. Setup Storybook.md +++ b/.github/custom-issue-template/frontend-kit/2. Setup Storybook.md @@ -1,6 +1,15 @@ # Background -Storybook is a great way to build, validate, and test components. We want to ship a working storybook instance with each kit. + +Storybook is a great way to build and test components in a sandbox. Most teams opt out of Storybook because it takes time to setup. We should make it easy to add stories and colocate them with their components. # Acceptance -- [ ] Install and configure storybook -- [ ] Add a simple example of storybook using the existing components \ No newline at end of file + +- [ ] Storybook setup: Add Storybook to the project and get it running. +- [ ] Remove default stories: Storybook ships with default stories. These should be removed as they are just examples that can be looked up later online. +- [ ] Add ability to colocate stories: Storybook needs some configuration to make colocated stories render correctly. The intention is you colocate a story file with the component it documents. Learn more here: https://storybook.js.org/docs/react/configure/overview +- [ ] Add ability to add page stories: Some people only focus on component-level stories while others try to do page level stories. We should provide a pattern for providing both. In metaframeworks, colocated page stories might not be possible so define a pattern for allowing for page level stories. +- [ ] Add good plugins: Storybook has a collection of plugins that are great for creating interactive stories. We should include some of the plugins including ones for accessibility, actions, and adjusting component inputs. See https://storybook.js.org/integrations for more details. + +# NOTE: + +Timebox: 8 hours (some newer technologies don't play well yet with Storybook, and we don't want to spin indefinitely) diff --git a/.github/custom-issue-template/frontend-kit/3. Add a greeting component page.md b/.github/custom-issue-template/frontend-kit/3. Add a greeting component page.md new file mode 100644 index 000000000..3e34bfd83 --- /dev/null +++ b/.github/custom-issue-template/frontend-kit/3. Add a greeting component page.md @@ -0,0 +1,16 @@ +# Background + +Routed as `/greet`. Accepts the query parameter `?greeting=` that can be used to customize the message displayed. Includes a title for the page and links back to the homepage. + +# Acceptance + +- [ ] Routed as `/greet` +- [ ] Accepts the query parameter `?greeting=` that can be used to customize the message displayed +- [ ] Includes a title for the page +- [ ] links back to the homepage +- [ ] A Storybook story for the page should be included + +# Notes: + +- If the kit supports SSR, the fetch should happen on the server and not the UI. +- Tests are not required. diff --git a/.github/custom-issue-template/frontend-kit/3. Add a home page component.md b/.github/custom-issue-template/frontend-kit/3. Add a home page component.md new file mode 100644 index 000000000..b7b265d7e --- /dev/null +++ b/.github/custom-issue-template/frontend-kit/3. Add a home page component.md @@ -0,0 +1,14 @@ +# Background + +A homepage (`/`) page that includes links that navigate to the different component specific pages. The title should be the kit’s name. + +# Acceptance + +- [ ] Create a home page component +- [ ] Includes links that navigate to different component specific pages +- [ ] The title is the kit's name +- [ ] A Storybook story for the page should be included. + +# Note: + +Tests are not required. diff --git a/.github/custom-issue-template/frontend-kit/3. Add counter component page.md b/.github/custom-issue-template/frontend-kit/3. Add counter component page.md new file mode 100644 index 000000000..1eceb63ae --- /dev/null +++ b/.github/custom-issue-template/frontend-kit/3. Add counter component page.md @@ -0,0 +1,15 @@ +# Background + +Routed as `/counter`. Loads the counter example onto the page. Includes a title for the page and links back to the homepage. + +# Acceptance + +- [ ] Routed as `/counter` +- [ ] Loads the counter example onto the page +- [ ] Includes a title for the page +- [ ] links back to the homepage +- [ ] A Storybook story for the page should be included + +# Note: + +Tests are not required. diff --git a/.github/custom-issue-template/frontend-kit/3. Add deployment instructions to README.md b/.github/custom-issue-template/frontend-kit/3. Add deployment instructions to README.md new file mode 100644 index 000000000..d8fdd5923 --- /dev/null +++ b/.github/custom-issue-template/frontend-kit/3. Add deployment instructions to README.md @@ -0,0 +1,7 @@ +# Background + +While we are not deploying these kits, instructions in the README on how to deploy them is requested. This can also be delivered as a blog post if it’s for a newer technology that doesn’t have a well defined deployment story. + +# Acceptance + +- [ ] The README includes instructions for deploying the kit diff --git a/.github/custom-issue-template/frontend-kit/3. Create a counter component.md b/.github/custom-issue-template/frontend-kit/3. Create a counter component.md index ad4d35551..f819baa2f 100644 --- a/.github/custom-issue-template/frontend-kit/3. Create a counter component.md +++ b/.github/custom-issue-template/frontend-kit/3. Create a counter component.md @@ -1,13 +1,17 @@ # Background + We want to launch each kit with an example of a component with state and good tests. We've chosen a counter for this reason. # Acceptance + - [ ] Create a counter component -- [ ] The counter should have an increment, decrement, and reset button +- [ ] The counter should have an increment, decrement, and reset (to zero) button - [ ] The counter should display its current value +- [ ] The counter should work in the negative direction as well - [ ] The counter should be controlled by the global state manager -- [ ] The counter should have a storybook story +- [ ] The counter should have a Storybook story - [ ] The counter should have a set of tests demonstrating how to verify all its features # Mock -![Screen Shot 2022-04-05 at 9 48 58 AM](https://user-images.githubusercontent.com/1815379/161781373-665295fa-5169-43e6-8dcb-a14c530c6b78.png) \ No newline at end of file + +![Screen Shot 2022-04-05 at 9 48 58 AM](https://user-images.githubusercontent.com/1815379/161781373-665295fa-5169-43e6-8dcb-a14c530c6b78.png) diff --git a/.github/custom-issue-template/frontend-kit/3. Create a fetch component.md b/.github/custom-issue-template/frontend-kit/3. Create a fetch component.md index 84ece8c9d..61c63e60e 100644 --- a/.github/custom-issue-template/frontend-kit/3. Create a fetch component.md +++ b/.github/custom-issue-template/frontend-kit/3. Create a fetch component.md @@ -1,16 +1,23 @@ # Background + We want to launch each kit with an example of a component that fetches data from a data source and related tests. We have an endpoint set up as a simple hello world that accepts a greeting for example sake. # Acceptance + - [ ] Create an API example component -- [ ] (if using REST)The component should make a GET request to `https://api.starter.dev/hello?greeting=` where the message is "framework-store-style starter.dev!" +- [ ] (if using REST)The component should make a GET request to `https://api.starter.dev/hello?greeting=` where the message is "framework-store-style starter.dev!" - [ ] (if using GraphQL) above equivalent using endpoint `https://api.starter.dev/graphql` -- [ ] The component should display the message from the API in the UI -- [ ] The component should have a storybook story +- [ ] When it successfully retrieves data the component should display the message from the API in the UI +- [ ] The message should be customizable +- [ ] When loading, display a loading state +- [ ] When an error occurs, display an error state +- [ ] The component should have a Storybook story - [ ] The component should have a set of reasonable tests demonstrating how to mock APIs # Note: + The mock shows RxJs but that is just because it was created for a different KIT. Use the tool chosen for you current Kit # Mock + ![image](https://user-images.githubusercontent.com/1815379/161786419-e05675bf-5fb8-42f6-ac0d-c23226d2e6cc.png) diff --git a/.github/custom-issue-template/frontend-kit/3. Update the readme.md b/.github/custom-issue-template/frontend-kit/3. Update the readme.md index 6603f8a9f..139fc9005 100644 --- a/.github/custom-issue-template/frontend-kit/3. Update the readme.md +++ b/.github/custom-issue-template/frontend-kit/3. Update the readme.md @@ -1,17 +1,39 @@ # Background -The kit should include a thorough README with all architectural decisions the user should be aware of when utilizing it. It shouldn't rewrite docs for existing libraries but any key decisions should be documented. This is what will be visible to users on the website when they look at the details page. + +The kit should include a thorough README with all architectural decisions the user should be aware of when utilizing it. It shouldn't rewrite docs for existing libraries but any key decisions should be documented. This is what will be visible to users on the website when they look at the details page. The README should include the following sections: + +- Overview + - What’s included in the kit + - Any key tooling provided +- Installation + - Getting started instructions including: + - Environment setup + - Running a local develop server +- Available Scripts and Commands + - Scripts available through the kit and their purpose + - Consider separating into sections +- Project Structure + - An explanation of the project directory structure so the consumer can understand how to extend it + - A list of default routes/features that the consumer can look at to understand the system +- Technology Specific Section(s) + - For each technology used, a section on key details of that technology such as additionally required configuration or key customizations to consider. + - Describe decisions around why certain decisions were or were not made. + - How to extend the app regarding the technology +- Deployment + - Recommended instructions for deploying the application. # Acceptance + - [ ] Update the below template with relevant information for users who want to utilize this kit with appropriate instructions. # Template > # starter kit -> +> > This starter kit features . -> +> > ## Table of Contents -> +> > - [Overview](#overview) > - [Tech Stack](#tech-stack) > - [Included Tooling](#included-tooling) @@ -21,62 +43,62 @@ The kit should include a thorough README with all architectural decisions the us > - [Manual](#manual) > - [Commands](#commands) > - [Demo Implementation](#demo-implementation) -> +> > ## Overview -> +> > ### Tech Stack -> +> > - List of technologies used with links to relevant doc pages -> +> > ### Included Tooling -> +> > - List of tooling used, e.g. jest, Storybook, ESLint, Prettier, etc., with their relevant doc pages linked > - [Jest](https://jestjs.io/) - Test runner > - [TypeScript](https://www.typescriptlang.org/) - Type checking > - [Storybook](https://storybook.js.org/) - Component library > - [ESLint](https://eslint.org/) - Code linting > - [Prettier](https://prettier.io/) - Code formatting -> +> > ### Architectural Decisions -> +> > List all important architectural decisions here and patterns users should be aware of. -> +> > ### Example Components -> -> In this `starters//src` directory you will find the directories. -> +> +> In this `starters//src` directory you will find the directories. +> > -> +> > ## Installation -> +> > ### CLI (Recommended) -> +> > ```bash > npx create-starter-dev > ``` -> +> > - Follow the prompts to select the starter kit and name your new project. > - `cd` into your project directory and run `npm install`. > - Run `npm run dev` to start the development server. > - Open your browser to `http://localhost:3000` to see the included example code running. -> +> > ### Manual -> +> > ```bash > git clone https://github.com/thisdot/starter.dev.git > ``` -> +> > - Copy and rename the `starters/` directory to the name of your new project. > - `cd` into your project directory and run `npm install`. > - Run `npm run dev` to start the development server. > - Open your browser to `http://localhost:3000` to see the included example code running. -> +> > ## Commands -> +> > - List of helpful package.json scripts and their purpose -> +> > ## Demo Implementation -> +> > [Repository](https://github.com/thisdot/starter.dev-showcases/tree/main/) -> -> The demo application re-implements some of GitHub's pages and functionality. It uses the OAuth credentials in GitHub to authenticate users with their GitHub accounts and uses RxJS to fetch data from the GitHub API. Check out the link above to learn more or check out the demo! \ No newline at end of file +> +> The demo application re-implements some of GitHub's pages and functionality. It uses the OAuth credentials in GitHub to authenticate users with their GitHub accounts and uses RxJS to fetch data from the GitHub API. Check out the link above to learn more or check out the demo! diff --git a/.github/custom-issue-template/frontend-kit/4. Add the kit to CLI run command.md b/.github/custom-issue-template/frontend-kit/4. Add the kit to CLI run command.md index 01916ca3a..b81e9b00b 100644 --- a/.github/custom-issue-template/frontend-kit/4. Add the kit to CLI run command.md +++ b/.github/custom-issue-template/frontend-kit/4. Add the kit to CLI run command.md @@ -2,5 +2,7 @@ Background At this point, the kit should be fully established and ready for an individual to use via the CLI. Acceptance + - [ ] Add the kit to the CLI as a setup option -- [ ] Test it locally with a fresh install \ No newline at end of file +- [ ] Test it locally with a fresh install +- [ ] The kit is released to npm diff --git a/.github/custom-issue-template/frontend-kit/5. Final checks.md b/.github/custom-issue-template/frontend-kit/5. Final checks.md new file mode 100644 index 000000000..5e36b0457 --- /dev/null +++ b/.github/custom-issue-template/frontend-kit/5. Final checks.md @@ -0,0 +1,10 @@ +# Background + +Once the kit has been finalized, we want to do a few final checks to make sure it meets the criteria in the specifications. + +# Acceptance + +- [ ] Set project to Use the latest version of Typescript +- [ ] A .nvmrc file should be provided with the kit to specify the node version used to ensure users are using the targeted node version. +- [ ] The lockfile from the project should be excluded to allow users to utilize their package manager of choice. The project should work equally well using any package manager. +- [ ] Because the lockfile is excluded, kits should pin their dependency version numbers to a fixed value. diff --git a/README.md b/README.md index 587b6b63e..219622ece 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ For proper integration with the starter-dev CLI and website there are also some ### Adding starter kit to the website -They `keyword` field in your starter kit's `package.json` categorizes/tags each starter kit on the website. For a reference of the keys that should be used here take a look at the`package/website/src/config.tsx` file. If a particular technology you're needing is missing from the`TECHNOLOGIES` list, please open a PR to add it including an icon _(if available)_. +They `keyword` field in your starter kit's `package.json` categorizes/tags each starter kit on the website. For a reference of the keys that should be used here take a look at the `package/website/src/config.tsx` file. If a particular technology you're needing is missing from the`TECHNOLOGIES` list, please open a PR to add it including an icon _(if available)_. Once you've added your description, keywords, and made sure the keywords exist in the `TECHNOLOGIES` list in the websites `config.tsx` file, your starter kit will automatically be added to the website and deployed once you merge into the `main` branch. @@ -68,6 +68,4 @@ Currently to add your starter kit to be an available option on the starter.dev C ### Starter kit README files -We are still working on defining a general structure and format for starter kit readme files. These are particularly important because the starter kit page on the website is based on the readme files. See: [next12-react-query-tailwind readme content #17](https://github.com/thisdot/starter.dev/pull/17) - -**WARNING**: Please do not add any comments to the README files. Comments in the markdown will cause the website builds to fail. +We are still working on defining a general structure and format for starter kit README files. These are particularly important because the starter kit page on the website is based on the README files. See: [next12-react-query-tailwind readme content #17](https://github.com/thisdot/starter.dev/pull/17) diff --git a/packages/website/src/layouts/KitLayout.astro b/packages/website/src/layouts/KitLayout.astro index f25916b32..61ca3ef35 100644 --- a/packages/website/src/layouts/KitLayout.astro +++ b/packages/website/src/layouts/KitLayout.astro @@ -65,7 +65,7 @@ const kit = parseKit(content); const articleEl = document.getElementsByTagName('article'); const articleLinkEls = articleEl[0]?.getElementsByTagName('a'); for (let anchor of articleLinkEls ?? []) { - // if it's not a link to content in readme, open in a new tab + // if it's not a link to content in README, open in a new tab const url = new URL(anchor.href); if (!url.hash) { anchor.target = '_blank';