Skip to main content

Development

Back to Documentation Intro Contents

info

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

Code Quality Practices​

Before diving into framework-specific tips, establish these habits that compound over time and prevent the most common solo-developer pitfalls.

for Solo Developers​

Working solo does not mean skipping code review. Use these techniques as your "second pair of eyes":

  • Self-review via PR: Always merge through a pull request and review your own diff before approving. Reading code in the PR view often surfaces issues you miss in the editor.
  • AI code review tools: Set up automated review on every PR:
    • CodeRabbit - AI-powered code review that catches bugs, security issues, and style problems
    • Cursor Bugbot - Automated bug detection integrated with Cursor
    • Graphite - PR workflow tools with AI review
Your AI Reviewer

Use AI code review tools (CodeRabbit, Cursor Bugbot) as your "second pair of eyes" on every PR. They catch issues that are easy to miss when you are deep in the code, and they cost nothing compared to shipping a bug.

​

  • Write code comments that explain why, not what. The code itself should explain what it does.
  • Keep your updated as your architecture evolves (see the /docs/decisions/ folder set up in Planning)
  • For public APIs, generate documentation from code annotations (JSDoc, TypeDoc) to keep docs in sync with implementation

Framework-specific Development Tips​

React​

React

Vite​

Vite

Next.js​

Next.js

Language-specific Development Tips​

HTML​

HTML5

  • Theme Colour

    • Set up your HTML head with some nice small tweaks
      • Use theme-colour and add your theme <meta name="theme-color" content="#f00" />
      • The theme-color doesn’t have to be unique within the page. It can be personalized using the media attribute to change colors depending on the browser’s/computer’s configuration. 
        <!-- theme color is white unless in dark mode, then it's black -->
        <meta name="theme-color" content="#fff" />
        <meta
          name="theme-color"
          media="(prefers-color-scheme: dark)"
          content="#000" />
    • With the accent-color property you can specify the predominant color for checkboxes, radio buttons, ranges, and even progress bars.

  • Meta Tags

    • Add open graph meta tags - but note that the values should be page-specific and should be updated when navigating between pages.

      <meta property="og:type" content="website" />
      <meta property="og:title" content="Page Title" />
      <meta property="og:description" content="Description of the page." />
      <meta property="og:url" content="link.to.be.displayed.when.shared" />
      <meta property="og:image" content="link.to.thumbnail.image" />

      <meta name="twitter:card" content="summary" />
      <meta name="twitter:title" content="Page Title" />
      <meta name="twitter:description" content="Description of the page." />
      <meta name="twitter:url" content="link.to.be.displayed.when.shared" />
      <meta name="twitter:image" content="link.to.thumbnail.image" />

  • enterkeyhint property of the virtual keyboard

    • enterkeyhint MDN
    • enterkeyhint is a new attribute of the HTML input tag. This attribute affects the style and behavior of the enter keys of the virtual keyboard. It is mainly used on devices such as mobile terminals and tablets, so that users can clearly know what action the enter key will perform. Typical values for this attribute are "enter", "done", "go", "next", "previous", "search", and "send". 📱
    • 🔎 For example, if you use the attribute in a search box enterkeyhint="search", when the user uses the search box on a mobile device, the enter key will change to "Search" and the user will be able to submit the search by clicking this key. 🔍 
      <form action="/search">
        <input type="text" enterkeyhint="search" name="q" />
        <input type="submit" value="Search" />
      </form>
    • In this example, the input field’s enterkeyhint property is set to “search”, so that on the mobile device’s virtual keyboard, the label of the enter key changes to “search”. 🔑 For enterkeyhint the possible values and their meanings are as follows:
      • “enter”: The default behavior, which generally means a newline operation. ↩️
      • “done”: Indicates that the input operation is completed, such as after filling the last field of the form, the button on the virtual keyboard may change to “done”. ✅
      • “go”: means to navigate to a new page or view, or to start a process. 🚦
      • “next”: Indicates that the user will move to the next input field, suitable for forms with multiple input fields. ➡️
      • “previous”: Indicates that the user will move to the previous input field, suitable for forms with multiple input fields. ⬅️
      • “search”: Indicates to initiate a search operation, applicable to the search box. 🔍
      • “send”: Indicates that a message or other type of text will be sent, suitable for chat or mail applications. 📤

  • Use the correct HTML <input type=""> attribute for the correct input type. There are 22 HTML input types.

CSS​

CSS

CSS Tips​

  • Add smooth scrolling (in CSS file);

    html {
      scroll-behavior: smooth;
    }

Recommendations: (from Robin Wieruch)

CSS-in-CSS​

  • - CSS Modules give you a way to encapsulate your CSS into component co-located modules. This way, styles don't leak accidentally into other components:

    import styles from './style.module.css';

    const Headline = ({ title }) =>
      <h1 className={styles.headline}>
        {title}
      </h1>

​

const Headline = ({ title }) =>
  <h1 className="text-blue-700">
    {title}
  </h1>

​

Personally I'd not recommended runtime CSS-in-JS anymore due to performance and other problems in server-side environments

  • Styled Components
  • StyleX by Facebook
import styled from 'styled-components';

const BlueHeadline = styled.h1`
  color: blue;
`;

const Headline = ({ title }) =>
  <BlueHeadline>
    {title}
  </BlueHeadline>

​

  • Zustand - State management library - It allows you to manage global application state which can be read and modified by any React component that is connected to its store(s).
  • Redux

Recommendations: (from Robin Wieruch)

  • useState/useReducer for co-located or shared state
  • opt-in useContext for enabling little global state
  • Zustand (or an alternative) for lots of global state

Data Fetching​

Routing​

Components​

  • Material UI - Component Library - yarn add @material-ui/core - https://material-ui.com/
  • React Bits Components - Various useful React components
  • shadcn/ui - https://ui.shadcn.com/
  • saas-ui
    • Getting started with SaaS UI is easy. First, you’ll have to install Chakra UI into your React project, then install SaaS UI, like this:
    • npm i @chakra-ui/react @emotion/react@¹¹ @emotion/styled@¹¹ framer-motion@⁶\
    • npm i @saas-ui/react
    • If yarn is more your jam, you can do this instead:
    • yarn add @chakra-ui/react @emotion/react@¹¹ @emotion/styled@¹¹ framer-motion@⁶\
    • yarn add @saas-ui/react

Animations​

In order of recommendation:

Charts​

In order of recommendation:

Other Libraries​

Image Tools, Generation and Modification​

Other Tools​

  • Responsively - A web app to quickly test and view your responsive websites across devices.
  • Documentation & API Reference Tools

Dependency Management​

Modern applications depend on hundreds of third-party packages. Managing these dependencies is a critical development activity.

​

  • Always commit lock files (package-lock.json, yarn.lock, pnpm-lock.yaml) to version control
  • They ensure every build uses exactly the same dependency versions, eliminating "works on my machine" issues

Vulnerability Scanning​

  • Set up automated vulnerability checking using Snyk, Dependabot, or Renovate
  • These tools automatically create PRs to update vulnerable packages
  • Run npm audit or yarn audit regularly as a manual check

Update Policy​

Define a cadence for dependency updates and stick to it:

  • Patch/minor versions: Accept automated PRs weekly (low risk)
  • Major versions: Review manually - check changelogs for breaking changes
  • Security patches: Apply immediately regardless of schedule
Dependency Hygiene

Never let dependencies go unpatched for months. Automated PRs from Dependabot or Renovate make this near-effortless. Stale dependencies are one of the most common sources of security vulnerabilities.

​

Be aware of the licences of your dependencies. Some licences (GPL, AGPL) have implications for commercial or closed-source software. Use npx license-checker to audit your dependency licences.

Security and Authentication​

Security​

Shift-Left Security

Security is not a phase - it is a practice. Scan code as you write it, not just before release. Use at least two security scanning tools for comprehensive coverage.

info

See Verify - Security Testing for more detail on the and security testing methodologies.

  • Set up repository security scanning via Snyk
    • Add the project to Snyk here
    • Check and close off all vulnerabilities
  • Also set up and use Trivy to scan the code for vulnerabilities as an additional security measure.
    • Set up Trivy to scan the code for vulnerabilities as part of the CI/CD pipeline.
  • Test against the - the most common security vulnerabilities in web applications

Authentication​

(Internationalisation)​

Documentation​

  • Set up documentation for the project via a README.md file
  • Write from scratch or use a template such as readme.so
  • Ensure that there is a Cursor rule for keeping the documentation up to date
  • Keep your up to date as the project evolves - every significant decision should be recorded
  • If building an API, generate from code annotations:
Definition of Done

A feature is not complete until it has appropriate documentation, error handling, and (if applicable) metrics. Undocumented code becomes legacy code - the next person to touch it (including future-you) will either waste time understanding it or rewrite it.

Analytics​

  • Set up analytics for the project if it requires it. Ask AI to define the best solution, however possible options include:
    • Umami
      • Benefits including being self-hosted, no tracking of users, no cookies, no data collection, no data sharing, no data selling
    • Google Analytics
      • Benefits including being free, easy to set up, and has a lot of features
    • GoatCounter

Issues and Debugging​

HTML, CSS and JavaScript Issues​

  • If you are trying to minify JavaScript files and you get the error Minify Failed: 'preserve_line' is not a supported option, then run the command "Minify" again in VSCode using CTRL + Shift + M.
    • If this still fails, open user settings in VSCode, change a value in the minify section and try to save the file again to force the minification.
    • Return the user settings options back once done.

React Issues​

  • For issues in React (including Vite and Next.JS):
    • General debugging - Debug React in VSCode
    • Issue 1 - Cannot be used as a JSX component 
      'SidebarItem' cannot be used as a JSX component.   Its type '(props: SidebarLink) => Element' is not a valid JSX element type.     Type '(props: SidebarLink) => Element' is not assignable to type '(props: any, deprecatedLegacyContext?: any) => ReactNode'.       Type 'Element' is not assignable to type 'ReactNode'.         Property 'children' is missing in type 'Element' but required in type 'ReactPortal'.
      Solution link

Deployment​

  • Set up deployment to the hosting service of choice
  • Recommend Netlify for a simple deployment
  • Set up additional Netlify integrations (e.g. Lighthouse, Checklinks, HTML Validate). Link is here once deployed. (!NOTE - Not yet got these working on a repo)
    • Must haves
      • LightHouse - Automatically run a Lighthouse audit on your website after every build.
      • Checklinks - Checklinks helps you keep all your asset references correct and avoid embarrassing broken links to your internal pages, or even to external pages you link out to.
      • HTML Validate - Validate HTML generated by your build.
    • Possible haves
      • Image Optim - Optimize images as part of your Netlify build process.
      • Is Website Vulnerable - A Netlify plugin that uses Snyk to test for security vulnerabilities in a website's JavaScript libraries.
      • Minify HTML - A plugin to add HTML minification as a post-processing optimisation in Netlify.
      • Snyk Security - A Snyk Netlify plugin to find and monitor new security vulnerabilities in JavaScript libraries (also see below).