Getting Started

This project is built with Contentful, Next.js, Tailwind CSS & Typescript.

System Requirements

• Node.js 22.23.4 or later

Setup

1. Install nvm

Follow nvm setup instructions here.

2. Install Node.js locally

nvm install 22.23.4
nvm use 22.23.4

3. Install yarn

npm install yarn -g

4. Install dependencies

Using --frozen-lockfile makes sure that the environment is consistent on any machine by installing the exact package versions listed in the yarn.lock.

yarn install --frozen-lockfile

5. Signup for a free Contentful account and create an organisation and within that create a space.

   We called our organization OPTF and the space Website.

   • For the site to build correctly you need to import our Content models and assets into your Contentful space. We have created some example content so you can get comfortable with our Contentful setup.

   • Add your space ID and content management token inside of contentful/config.json

   • Run this command inside the root of this project

     npx contentful space import --config contentful/config.json
   

   • For more information about importing/exporting in Contentful see here.

6. Setup your environment file. See our .env.example as a guide. Make sure to call the file .env.local.

Developing

• For accessbility testing we use the axe-react plugin.
• We use the Headwind VSCode extension for sorting TailwindCSS classes.
• We use classnames to organise our classes into groups that combine at build time.

If you are new to Next.js, this is a helpful introduction: https://nextjs.org/docs

Now you can run the development server:

yarn dev

Open http://localhost:3000 with your browser to see the OPTF homepage.

You can start editing the page by modifying pages/index.js. The page auto-updates as you edit the file.

Committing changes

Before a commit is accepted the staged changes will be formatted using prettier and linted using eslint. The commit will be reverted if files are formatted or lint errors are returned.

Commit Message Convention

This project follows Conventional Commits

Commit messages will be checked using husky and commitlint.

Contentful

• Use the Link Preview and Media content models for embedding content into blog posts.
• If linking content that is on the site itself try to omit omit https://optf.org. e.g. https://optf.org/blog/onion-requests-session-new-message-routing-solution/ => /blog/onion-requests-session-new-message-routing-solution/.
• To use ^superscript, _subscript, strikethroughs or style text use the Markup content model.

Next.js

• Try to use the next/image component in place of img tags where possible. It must have the unoptimized prop: next export has no image optimizer.
• If you want to make a link to a location on the website use the next/link component with a relative path. i.e. https://optf.ngo/blog -> /blog

TailwindCSS

Class organisation

This helps with readability and is encouraged. Consider it to be a guideline and not a set of rules.

React Component

  <div className={classNames(
    "general classes here - colors, fonts, padding, margin etc",
    "responsive class changes should have it's own string md: lg: etc."
    "placeholder classes",
    "animations, transforms, effect",
    "pseudo classes i.e hover, focus, active, etc.",
    "toggling classes i.e. NavMenu isExpanded"
  )}></div>

Custom CSS Class

.custom-class {
  @apply general classes here - colors, fonts, padding, margin etc;
  @apply responsive class changes should have it's own string md: lg: etc.;
  @apply placeholder classes;
  @apply animations, transforms, effect;
  @apply pseudo classes i.e hover, focus, active, etc.;
  @apply toggling classes i.e. NavMenu isExpanded;
}

Issues with Tailwind

We can't use template literals with classes if we want to purge (shrink) the CSS files at build time.

<div className="hover:bg-black hover:text-${bgColor}"></div> // Won't work in production

• tailwindlabs/tailwindcss#2209 (comment)
• https://tailwindcss.com/docs/optimizing-for-production#writing-purgeable-html

Deploying to Production

yarn build

This runs next build then next export, which writes a fully static site to out/. Serve that directory with any web server; no Node.js process runs in production. Content changes on Contentful need a rebuild.

next export does not apply headers, redirects or rewrites, so the web server must:

• serve clean URLs: /blog from blog.html, / from index.html, and redirect /path/ to /path
• serve blog posts at /blog/:slug from :slug.html (/:slug also works)
• redirect (308) /transparency to /transparency-report, and the removed /contact-us and /feedback-and-ideas pages to /blog/the-optf-and-session
• serve 404.html for unknown paths
• send the security headers, including the Content Security Policy

yarn build:staging builds the same export with staging metadata (https://staging.optf.ngo). It has no access control of its own; protect it at the web server if needed.

License

Distributed under the GNU GPLv3 License. See LICENSE for more information.