Initiation

Back to Documentation Intro Contents

info

See Code for more information on the code (implementation) phase of the SDLC.

Create the New App

Boilerplate Code

• Consider using code to get started, as listed here

CRA (Create React App)

• npx create-react-app my-app - Create a new React app called "my-app"
• npx create-react-app my-app --template typescript - Create a new React app called "my-app" with TypeScript
• cd my-app - Change directory to the new React app
• npm start - Start the React app
• npm run build - Build the React app for production

Vite

• To use Vite with Yarn and TypeScript do the following;
  • yarn create vite my-app --template react-ts
  • Then follow the instructions in the terminal
    • Note: For "package name" use the name of the app
  • For other possible Vite options see here
• cd my-app - Change directory to the new React app
  • yarn - Install the dependencies
  • yarn dev - Start the React app
  • yarn build - Build the React app for production

Next.js

• JavaScript and npm
  • npx create-next-app@latest - Create a new Next.JS app (name will be requested)
  • cd xxx - Change directory to the new Next.JS app replacing the xxx with the name of the app
  • npm install - Install the dependencies
  • npm run dev - Start the React app
  • npm run build - Build the React app for production
• Typescript and yarn
  • yarn create next-app --typescript - Create a new Next.JS app with TypeScript (name will be requested)
  • cd xxx - Change directory to the new Next.JS app replacing the xxx with the name of the app
• yarn - Install the dependencies
  • yarn dev - Start the React app
  • yarn build - Build the React app for production

Initiate a Git Repository and link to GitHub

• Create a new repository on GitHub
• In the app terminal, initiate git and push to GitHub (replace the below GitHub URL with your own);

git init
git remote add origin https://github.com/bangsluke/hacker-stories.git
git branch -M main
git commit -m "Initial commit"
git push -u origin main

• Make the repo private or public based on the requirements
• Add a .gitignore file to the root of the project

Choose a branching strategy and stick to it from the start:

• Recommended for solo developers: - create short-lived feature branches off main, merge via pull requests after review
• Alternative: with a develop branch - more ceremony, but useful if you want a staging buffer before production

Branch Protection

Set up on your main branch:

• Require pull requests before merging (no direct pushes)
• Require status checks to pass (CI pipeline) before merging
• In GitHub: Settings > Branches > Add branch protection rule for main

Solo Dev PRs

Even working solo, use pull requests. They create a review checkpoint, a searchable history of changes, and a natural place for AI code review tools to provide feedback. A PR also ensures your CI pipeline runs before code reaches main.

Structure and File Setup

Folder and File Structure

Folder Structure

• Create a folder structure that makes sense for the project
  • For a React project, have the following set up

    Note, this structure is based off of the Bulletproof React project

src
|
+-- /assets            # Assets folder can contain all the static files such as images, fonts, etc.
+-- /components        # Shared components used across the entire application
+-- /config            # All the global configuration, env variables etc. get exported from here and used in the app
+---- .env             # Environment variables
+-- /data              # Any stored data that is used across the application (my own addition)
+-- /features          # Feature based modules
+-- /hooks             # Shared hooks used across the entire application
+-- /lib               # Re-exporting different libraries preconfigured for the application
+-- /providers         # All of the application providers
+-- /routes            # Routes configuration
+-- /stores            # Global state stores
+-- /test              # Test utilities and mock server
+-- /types             # Base types used across the application
+-- /utils             # Shared utility functions

• For a Next project, consider which folders are not needed, e.g. Routes would not be needed as Next handles routing via the pages folder
• To set up the above structure, first, navigate to the root folder of your project and then run the command from the linked file in the terminal
  • Folder Structure Command.md

Component Set Up

See point 4 of 10 Best Practices in Front End Development (React)

Structure your components in the following way, using Export Barrelling (point 2);

--components:
----Button
------index.ts (exports everything necessary)
------types.ts
------styles.css
------utils.ts
------component.tsx
----Icon
------index.ts (exports everything necessary)
------types.ts
------styles.css
------utils.ts
------component.tsx
----Input
------index.ts (exports everything necessary)
------types.ts
------styles.css
------utils.ts
------component.tsx

File Set Up

• Also, it is best practice to have a certain few files within your project

Note, these files are already created in the above command

• README.md file in the root of the project echo "# Project" > README.md

• An empty .env file in the root of the project

  echo "# Add an API Key" > .env
  echo "API_KEY=AddKey" >> .env

• .gitignore file in the root of the project

  echo "# local env files" > .gitignore
  echo ".env" >> .gitignore

  • Gitignore.io is a great resource to generate a .gitignore file for your project

Files and Variables

• To securely store environment variables, create a .env file in the root of the project
• Then create a .gitignore file in the root of the project and add the .env file to it
• For CRA, you can create .env variables named as REACT_APP_ and they will be available in the browser
  • Example: REACT_APP_API_KEY=1234567890
  • You can then use the variable in the code as process.env.REACT_APP_API_KEY
  • See this article
• For Vite, you can create .env variables named as VITE_ and they will be available in the browser
  • Example: VITE_API_KEY=1234567890
  • You can then use the variable in the code as import.meta.env.VITE_API_KEY
  • See this article
• For Next.JS;
  • Example: API_KEY=1234567890
  • If you're just working in Node.JS, you can then use the variable in the code as process.env.API_KEY
  • If you're working in the browser, you have to prefix the variable in the code as process.env.NEXT_PUBLIC_API_KEY
  • See this article
  • Read this Medium story if still have issues

References

1. Hiding Secret Keys in React

Set up pre-commit hooks to catch issues before code ever reaches a pull request. Use Husky + lint-staged to automate this:

npx husky init
npm install --save-dev lint-staged

Configure lint-staged in your package.json to run on staged files:

"lint-staged": {
  "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
  "*.{json,md,css}": ["prettier --write"]
}

Your pre-commit hooks should run:

• Linting and formatting - catch style violations instantly
• Type checking - if using TypeScript, run tsc --noEmit
• Secrets scanning - use gitleaks or git-secrets to prevent accidental credential commits

info

See Code - Pre-Commit Hooks for more detail on what to include in pre-commit hooks.

and Config

• Copy over the .eslintrc.json and .prettierrc set ups from a good project (e.g. Dorkinians Mobile Stats)
• Make changes if any are required
• Adopt an established rather than inventing your own:
  • JavaScript/TypeScript: Airbnb or Standard
  • React: Extend the Airbnb config with eslint-config-airbnb
• Consider the below references if needed

info

See Code - Code Quality for more detail on coding standards and how they prevent bugs.

References

1. React + TypeScript + ESLint + Prettier Full Setup
2. How to properly set up Prettier in less than 2 minutes

React Set Up

If using React, consider the following links:

• Don't use React imports like this. Use Wrapper Pattern instead - wrapper to go around library imports

• Create the folder structure .github/workflows at the root folder
• Copy over the workflow .yml files from a good project (e.g. Dorkinians Mobile Stats)
  • CI.yml
  • CD.yml
  • CodeQL.yml
  • dependencyReview.yml
  • dependabot.yml
• Modify any details of the workflow to suit your needs
• Add automated linting to CI/CD
  • Super Linter GitHub

Design

info

See Integrate - CI Pipeline Design for comprehensive CI pipeline guidance.

Structure your CI pipeline to follow this order (cheapest/fastest checks first):

1. Lint and Format - catch style violations instantly
2. Type Check - catch type errors (tsc --noEmit)
3. Build - verify the app compiles
4. Unit Tests - run fast, isolated tests
5. Integration Tests - verify cross-module contracts
6. Security Scan - check for known vulnerabilities (CodeQL, Snyk)
7. Deploy - only if all above pass

Fail Fast

Order your CI pipeline so the fastest checks run first. If linting fails in 10 seconds, there is no point running a 5-minute test suite. This saves CI minutes and gives you faster feedback.

Automated Dependency Updates

Set up or Renovate to keep dependencies current:

• Dependabot: Add a dependabot.yml to .github/ (already included in the workflow files above)
• Configure it to open PRs weekly for patch/minor updates and flag major updates for manual review
• Never let dependencies go unpatched for months - automated PRs make this near-effortless

Cursor/Antigravity Project Rules

If using either Cursor or Antigravity, you will already have a User Rule/Global Rule set up (see my Obsidian note on AI Prompts here).

For setting up the Project Rules, you can follow the notes in the Obsidian notes or follow below:

• To set up Project rules, open the project in Cursor and then follow the instructions in the following link to automatically set up the correct Project rule files for your project.
  • GitHub - Renvia-code/best-cursor-rules: Best Cursor Rules is a curated collection of 33 high-quality Cursor AI rules that actually work. Includes a Setup Wizard that analyzes your project and generates customized rules automatically.
• Answer the questions in the Setup Wizard to generate the correct Project rule files for your project.

note

If you are using Antigravity, ensure that you copy the rules generated in Cursor over into the Rules section of Antigravity - Settings.

Development Environment Consistency

Ensure that anyone (including future-you) can set up and run the project quickly and reliably.

Minimum: Documented Setup

• Include a clear "Getting Started" section in your README with every command needed to run the project from a fresh clone
• Specify the required Node.js version (use a .nvmrc or .node-version file)
• List any system-level dependencies (e.g. database, Redis)

Recommended:

For any project you might hand off or return to after a break, consider a Dev Container configuration:

• Create a .devcontainer/devcontainer.json in the project root
• Specify the base image, extensions, port forwarding, and post-create commands
• Works with VS Code, Cursor, and GitHub Codespaces

note

For solo projects, a well-written README setup section is the minimum. For any project you might hand off to someone else or return to after months, a Dev Container config eliminates "works on my machine" problems entirely.