|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Hey there! We're excited that you're interested in contributing to Create Next Stack. This document should help you get set up locally and guide you through the process of contributing. |
| 4 | + |
| 5 | +## Table of Contents |
| 6 | + |
| 7 | +- [Getting Started](#getting-started) |
| 8 | +- [Repository Overview](#repository-overview) |
| 9 | +- [Creating a pull request](#creating-a-pull-request) |
| 10 | +- [Adding support for a new technology](#adding-support-for-a-new-technology) |
| 11 | +- [Writing a plugin](#writing-a-plugin) |
| 12 | + |
| 13 | +## Getting Started |
| 14 | + |
| 15 | +Before you start contributing, you'll need to get the project set up locally. Follow the steps below to get started. |
| 16 | + |
| 17 | +1. Make sure you have the latest [Node.js](https://nodejs.org/en/) and [Git](https://git-scm.com/) installed. |
| 18 | +2. Install [pnpm](https://pnpm.io/) using `npm i -g pnpm`. |
| 19 | +3. Fork the repository on GitHub. |
| 20 | +4. Clone your forked repository locally. |
| 21 | +5. Install dependencies using `pnpm install`. |
| 22 | +6. Build the project using `pnpm run build`. |
| 23 | + |
| 24 | +## Repository Overview |
| 25 | + |
| 26 | +This repository is a [monorepo](https://en.wikipedia.org/wiki/Monorepo) managed using [pnpm](https://pnpm.io/). This means that there are multiple packages in the repository, each with their own `package.json` file. The `package.json` file in the root of the repository is used to manage the packages in the repository. |
| 27 | + |
| 28 | +You can see where the monorepo looks for packages in the `pnpm-workspace.yaml` file: |
| 29 | + |
| 30 | +```yaml |
| 31 | +packages: |
| 32 | + - "packages/**" |
| 33 | + - "website" |
| 34 | +``` |
| 35 | +
|
| 36 | +Packages that are published to npm are located inside the [`packages`](packages) directory. A single [`website`](website) package is located outside of the `packages` directory, as it is not published to npm. The `website` package is used to build the [create-next-stack.com](https://create-next-stack.com/). |
| 37 | + |
| 38 | +You can find a list of generally useful npm scripts available in the root by checking out the root [`package.json`](package.json) file. |
| 39 | + |
| 40 | +A couple of notable scripts that allow you to build, lint, and test the entire repository, or specific packages are: |
| 41 | + |
| 42 | +- `build` |
| 43 | +- `build:cli` |
| 44 | +- `build:web` |
| 45 | +- `lint` |
| 46 | +- `lint:cli` |
| 47 | +- `lint:web` |
| 48 | +- `test` |
| 49 | +- `test:cli` |
| 50 | +- `test:web` |
| 51 | + |
| 52 | +Each package has its own `package.json` file, which contains scripts specific to that package. The above list are just wrapper scripts that call the underlying packages' `build`, `test`, and `test` scripts. |
| 53 | + |
| 54 | +Note that running scripts inside a specific package's directory will only run the script for that package. For example, running `pnpm run build` inside the `packages/create-next-stack` directory will run the `build` script specified in the `create-next-stack` package's `package.json` file. |
| 55 | + |
| 56 | +## Creating a Pull Request |
| 57 | + |
| 58 | +Make sure you are set up locally by following the [Getting Started](#getting-started) section above. |
| 59 | + |
| 60 | +1. Create a new branch from `develop` with a descriptive name. |
| 61 | +2. Make your changes. |
| 62 | +3. Run tests using `pnpm test` to ensure they all pass. |
| 63 | +4. [Submit a Pull Request](https://github.com/akd-io/create-next-stack/compare). |
| 64 | + |
| 65 | +## Adding Support for a New Technology |
| 66 | + |
| 67 | +Make sure you are set up locally by following the [Getting Started](#getting-started) section above. |
| 68 | + |
| 69 | +1. Create a new branch from `develop` with a descriptive name. |
| 70 | + |
| 71 | + - `git checkout -b feature/support-my-favorite-technology` |
| 72 | + |
| 73 | +2. Useful npm scripts of `packages/create-next-stack` to run during development: |
| 74 | + |
| 75 | + - `check-types:watch` - Runs TypeScript in watch mode to check types as you make changes. You can run this instead of `build:watch` while working on the CLI, as the e2e tests do just-in-time compilation via `ts-node`. |
| 76 | + - `jest:watch` - Runs Jest in watch mode to run unit tests as you make changes. |
| 77 | + - These tests were specifically made to ease the plugin authoring process, so don't forget this one. |
| 78 | + - `test` - Runs e2e tests. Note that this will run all e2e tests, which can take quite a while. |
| 79 | + - `lint` - Runs ESLint to lint the project. |
| 80 | + - `test:manual` |
| 81 | + - For example, `pnpm run test:manual --package-manager=pnpm --styling=emotion`. |
| 82 | + - Sets up a new directory for a test run of the CLI, runs the CLI with the specified flags, and builds the generated Next app, and checks formatting and linting. |
| 83 | + - This is useful for manually testing the CLI. Pass whatever flags to the CLI that you want to test. The `app_name` argument will be set automatically. |
| 84 | + - `test:raw` - Runs the binary directly. Rarely used, but can be useful for manual tests where you want to be able to specify the `app_name` argument yourself. |
| 85 | + - `clean` - Removes all generated files, including build files and the `create-next-stack-tests` directory created by the e2e tests. |
| 86 | + |
| 87 | +3. Add a new .ts file for your plugin in the plugins directory at `packages\create-next-stack\src\main\plugins` |
| 88 | + |
| 89 | + - See the [Writing a plugin section](#writing-a-plugin) below to learn how to write a Create Next Stack plugin. |
| 90 | + |
| 91 | +4. Add new flags to the `create-next-stack` command in [`create-next-stack.ts`](packages\create-next-stack\src\main\commands\create-next-stack.ts). |
| 92 | +5. Add the plugin to the `plugins` array in [`setup.ts`](packages/create-next-stack/src/main/setup/setup.ts). |
| 93 | +6. Add potential plugin steps to the `steps` array in [`setup.ts`](packages/create-next-stack/src/main/setup/setup.ts). Steps are run top-to-bottom. |
| 94 | +7. Update the [`README.md`](README.md): |
| 95 | + - Add the technology to the technology list |
| 96 | + - Update the `Usage` section by copy pasting the output of running `yarn print:help` |
| 97 | +8. Consider expanding some of the e2e tests to include the new technology. See [`test.ts`](packages\create-next-stack\src\tests\e2e\test.ts) for current tests. |
| 98 | +9. Run tests using `yarn test` to ensure they all pass. |
| 99 | +10. Submit a Pull Request on GitHub. |
| 100 | + |
| 101 | +## Writing a Plugin |
| 102 | + |
| 103 | +Plugins aren't too scary. A Create Next Stack plugin consists of a simple TypeScript file that calls a `createPlugin()` function with JSON object. |
| 104 | + |
| 105 | +See the [Framer Motion plugin](packages/create-next-stack/src/main/plugins/emotion.ts) for example. This plugin adds the `framer-motion` npm dependency to the generated Next.js project, as well as adding some documentation about the technology. |
| 106 | + |
| 107 | +```typescript |
| 108 | +export const framerMotionPlugin = createPlugin({ |
| 109 | + id: "framer-motion", |
| 110 | + name: "Framer Motion", |
| 111 | + description: "Adds support for Framer Motion", |
| 112 | + active: ({ flags }) => Boolean(flags["framer-motion"]), |
| 113 | + dependencies: { |
| 114 | + "framer-motion": { |
| 115 | + name: "framer-motion", |
| 116 | + version: "^9.0.0", |
| 117 | + }, |
| 118 | + }, |
| 119 | + technologies: [ |
| 120 | + { |
| 121 | + id: "framerMotion", |
| 122 | + name: "Framer Motion", |
| 123 | + description: |
| 124 | + "Framer Motion is a popular React animation library. It allows users to create both simple animations and complex gesture-based interactions. The library implements a declarative API, otherwise known as spring animations, which lets the developer define the animation's end state, letting the library handle the rest.", |
| 125 | + links: [ |
| 126 | + { title: "Website", url: "https://www.framer.com/motion/" }, |
| 127 | + { title: "Docs", url: "https://www.framer.com/docs/" }, |
| 128 | + { title: "GitHub", url: "https://github.com/framer/motion" }, |
| 129 | + ], |
| 130 | + }, |
| 131 | + ], |
| 132 | +} as const) |
| 133 | +``` |
| 134 | + |
| 135 | +Below is a breakdown of the `createPlugin()` function's JSON object: |
| 136 | + |
| 137 | +- The `name` property is the name of the plugin. |
| 138 | +- The `description` property is a short description of the plugin. |
| 139 | +- The `active` property is a function that returns a boolean indicating whether the plugin should be active. This function is passed the `flags` object, which contains all the flags passed to the `create-next-stack` command. |
| 140 | +- The `dependencies` property is an object containing the npm dependencies that should be added to the generated Next.js project. The key and `name` property is the name of the dependency, and the `version` property is version of the dependency. |
| 141 | +- The `technologies` property is an array of objects containing information about the technology. The `name` property is the name of the technology. The `description` property is a short description of the technology. The `links` property is an array of objects containing links to the technology's website, documentation, and GitHub repository. |
| 142 | + |
| 143 | +Some of these properties are optional, and some are required. Some properties are used by the CLI, some are used by the website, and some both. It's not too important to know everywhere these properties are used. As long as we specify as many properties as possible, the CLI and website is going to find out how to use it. |
| 144 | + |
| 145 | +For a complete list of properties that can be passed to the `createPlugin()` function, their explanations, and usage, see the [`Plugin` type definition](packages/create-next-stack/src/main/plugin.ts). You should find all the documentation you need there. If not, please [open an issue](https://github.com/akd-io/create-next-stack/issues/new). |
| 146 | + |
| 147 | +For more examples, please take a look at the [existing plugins](packages/create-next-stack/src/main/plugins). |
0 commit comments