Build Carrd

The build, in order

1. 1

   Build pipeline

   hideshow

   Prove the whole idea in the smallest form: content.json goes in, an HTML page comes out, and a mistake in the JSON fails loudly instead of rendering a half-empty page.

   1. 1.1Create the project folder and initialise it

      Everything lives in one folder. The type: module line lets you use import syntax in the build script.

      Files package.json

      terminalcopy

      mkdir my-site && cd my-site
      git init
      npm init -y
      npm pkg set type=module
      mkdir public

   2. 1.2Write content.json with every key the site will use

      Fill it with your real content from the prerequisites. Keep projects and socials as arrays even if you only have one.

      Files content.json

      {
        "name": "Ada Lovelace",
        "headline": "I write software that explains itself.",
        "about": "Three to five sentences about you.",
        "avatar": "/avatar.jpg",
        "accent": "#5b8def",
        "email": "you@example.com",
        "socials": [{ "label": "GitHub", "url": "https://github.com/you", "icon": "github" }],
        "projects": [{ "title": "A project", "description": "One sentence.", "url": "https://example.com" }],
        "seo": { "title": "Ada Lovelace", "description": "One line for search results." }
      }

   3. 1.3Write build.mjs: read the JSON, render index.html, copy public/

      Use a template literal for the HTML. Escape every value from the JSON before inserting it (replace &, <, > with their entities) so a stray character in your bio cannot break the page. Write to dist/index.html and copy public/ into dist/.

      Files build.mjs

   4. 1.4Validate content.json before rendering

      At the top of build.mjs, check that name, headline, about, avatar, email and seo exist and that every url starts with http. On failure, print which key is wrong and exit with code 1. A build that renders a page with a missing name is the failure this step prevents.

      Files build.mjs

   5. 1.5Add the build script and run it
      terminalcopy

      npm pkg set scripts.build="node build.mjs"
      npm run build
      npx serve dist

   done when · tick each as it passes

   • npm run build creates dist/index.html and the page opens in a browser at the URL serve prints
   • Changing name in content.json and running the build again changes the heading on the page
   • Deleting the headline key from content.json makes the build exit with an error naming headline
   • A project description containing a < character renders as text, not as broken markup

   watch out

   • Do not reach for a framework or a bundler here. The output is one HTML file; a build tool would be the heaviest part of the project.
   • Escape JSON values on the way into the HTML. This is the one place the page can be broken by its own content.

   next phase
2. 2

   Design layer

   hideshow

   Make it look designed rather than templated, with one inlined stylesheet, and prove it on three screen widths.

   1. 2.1Create styles.css and inline it into the HTML at build time

      Read the file in build.mjs and place its contents inside a style tag in the head. One request fewer, and the page paints with its styles on the first byte.

      Files styles.cssbuild.mjs

   2. 2.2Set the typographic scale with clamp() and a system font stack

      Headline around clamp(2rem, 6vw, 4rem), body 1.05rem with line-height 1.65, a measure of about 60 characters for paragraphs. No web fonts: they cost a request and Lighthouse points, and the system stack looks native everywhere.

   3. 2.3Read the accent color from content.json into a CSS custom property

      In build.mjs, write :root { --accent: <value> } into the inlined stylesheet. Use var(--accent) for links, focus rings and one decorative element. Changing the hex in content.json is the only way the theme changes.

   4. 2.4Add dark mode with prefers-color-scheme

      Define the light palette on :root and override the same custom properties inside @media (prefers-color-scheme: dark). Check contrast in both: the accent on both backgrounds must pass 4.5:1 for text.

   5. 2.5Add hover and focus-visible states to every link and button

      A visible focus ring on every interactive element, using the accent. Keyboard visitors must be able to see where they are.

   done when · tick each as it passes

   • The page looks intentional at 375px, 768px and 1440px wide with no horizontal scrollbar at any of them
   • Switching the operating system to dark mode changes the page and every piece of text still reads clearly
   • Tabbing through the page shows a visible focus ring on every link
   • The built page makes zero requests for fonts or stylesheets: everything is in the one HTML file

   watch out

   • Self-host or skip web fonts entirely. A fonts.googleapis.com request is a third-party call, a privacy question and a Lighthouse deduction all at once.

   next phase
3. 3

   Content blocks

   hideshow

   Render the socials and projects from their arrays, and make an empty array disappear completely instead of leaving a stray heading.

   1. 3.1Build an inline SVG sprite for social icons

      One svg element with a symbol per icon (github, x, linkedin, mastodon, email, website), hidden at the top of the body. Each social link uses a use element pointing at its symbol. No icon font, no external request.

      Files icons.svgbuild.mjs

   2. 3.2Render the socials row from content.json

      Map socials to links with the icon and an aria-label of the label. If the array is empty, render nothing at all: no wrapper, no heading.

   3. 3.3Render the projects grid from content.json

      A responsive grid (auto-fit, minmax(240px, 1fr)) of cards with title, description and the link. Same rule: empty array, no section.

   4. 3.4Add rel="noopener noreferrer" and target="_blank" to outbound links

      Every URL in content.json points off your site. Opening in a new tab is the expected behaviour for a link page; noopener is the security half of that.

   done when · tick each as it passes

   • With three socials and two projects in content.json both sections render with the right icons and links
   • Setting projects to [] and rebuilding leaves no trace of the section: no heading, no empty grid, no extra spacing
   • Every outbound link opens in a new tab and carries rel="noopener noreferrer" in the built HTML

   next phase
4. 4

   Contact form

   hideshow

   A working contact form with no third-party service: the small server appends each message to a log file and shows an inline thank-you, and it turns away the obvious bots.

   1. 4.1Write server.mjs with node:http that serves dist/ and handles POST /contact

      Serve files from dist/ for GET requests. For POST /contact, read the body (cap it at 4 KB), parse the form fields, and append one JSON line with a timestamp to the file named in MESSAGES_LOG. Respond by redirecting back to /#thanks so the page shows the inline thank-you.

      Files server.mjs

      terminalcopy

      npm pkg set scripts.start="node --env-file=.env server.mjs"

   2. 4.2Create .env from .env.example and start the server

      Node 22 reads .env with the --env-file flag, so no dotenv dependency is needed.

      Files .env

      terminalcopy

      cp .env.example .env
      npm start

   3. 4.3Add the form to the page with a honeypot field

      Fields: name, email, message, plus a text input named website that is hidden with CSS (position absolute, left -9999px), not type=hidden. Real people never see it; bots fill it. The form must work as a plain HTML POST with JavaScript disabled.

   4. 4.4Reject bots: honeypot, minimum fill time, size cap

      If website is filled, respond with the same thank-you but write nothing. Put a hidden timestamp in the form and reject submissions arriving faster than FORM_MIN_SECONDS. Reject bodies over 4 KB with a 413.

   5. 4.5Rate limit by IP in memory

      A Map of IP to an array of timestamps; allow FORM_RATE_LIMIT submissions per rolling hour, respond 429 beyond that. In-memory is fine: a restart resetting the counters costs nothing here.

   6. 4.6Render the inline thank-you

      A #thanks element hidden by default; the :target CSS pseudo-class shows it when the redirect lands on /#thanks. No JavaScript required.

   done when · tick each as it passes

   • Submitting the form appends exactly one JSON line to messages.log and the page shows the thank-you
   • Filling the hidden website field shows the same thank-you and appends nothing
   • A submission sent within one second of the page loading is rejected
   • The sixth submission from the same address inside an hour gets a 429
   • The form still submits and shows the thank-you with JavaScript disabled in the browser

   watch out

   • Do not use type=hidden for the honeypot: bots know to skip those. Hide it with CSS so it looks like a real field to a script.
   • Never write the raw request body to the log. Parse the fields, then write only the fields you expect.

   next phase
5. 5

   Share cards and performance

   hideshow

   The page previews properly when shared, and scores 100 on Lighthouse for Performance, Accessibility and Best Practices.

   1. 5.1Add Open Graph and Twitter meta tags from seo in content.json

      og:title, og:description, og:image, og:url (built from SITE_URL), twitter:card summary_large_image. Absolute URLs only: relative ones do not work in share previews.

   2. 5.2Generate a 1200x630 OG image at build time

      Install satori and @resvg/resvg-js, render your name and headline on your accent color to SVG then PNG, write dist/og.png. Pin the versions in package.json.

      Files build.mjsdist/og.png

      terminalcopy

      npm install satori@0.29.0 @resvg/resvg-js@2.6.2

   3. 5.3Run Lighthouse and fix what it names

      DevTools > Lighthouse > Analyze page load, on the built page served by npm start. Typical fixes: an image without width and height attributes, a contrast miss, a missing lang attribute on html.

   4. 5.4Set width and height on the avatar and compress it

      Resize the avatar to 320x320 and save as WebP with a JPG fallback. Explicit dimensions stop layout shift, which is a Performance deduction.

   done when · tick each as it passes

   • Lighthouse reports 100 for Performance, Accessibility and Best Practices on the built page
   • Pasting the page URL into a card validator (or a Slack message) shows the generated OG image and the right title
   • The built HTML is under 30 KB and makes no third-party requests

   watch out

   • Run Lighthouse against the built site served by your server, not against a file:// URL or the dev preview. The scores differ.

   next phase
6. 6

   Deploy and document

   hideshow

   The site is live on your domain with a working form, and the README lets someone else run it without asking you anything.

   1. 6.1Choose the deploy path and write it down

      Path A, one VPS: Caddy serves dist/ and proxies /contact to the Node server, with a systemd unit for the server. Path B, static host plus function: dist/ on Cloudflare Pages or Netlify, and the form handler as a function writing to a KV store or emailing you. Pick one; the README documents that one.

   2. 6.2Path A: add the Caddyfile and the systemd unit

      Caddyfile: your domain, file_server on dist, reverse_proxy /contact to localhost:PORT. Unit: Restart=on-failure, EnvironmentFile pointing at .env, running as an unprivileged user.

      Files Caddyfiledeploy/site.service

   3. 6.3Point the domain at the host

      One A record (VPS) or the CNAME the static host gives you. Wait for it to resolve, then load the site over https.

   4. 6.4Write the README

      Sections: what this is, the content.json key reference with which keys are required, how to build and run, where messages land and how to read them, the deploy path you chose, and one line stating this replaces Carrd's output rather than Carrd's editor.

      Files README.md

   5. 6.5Do a clean-clone test

      Clone the repo into a fresh folder, follow only the README, and get to a running site with a working form. Fix every step the README skipped.

      terminalcopy

      git clone <your-repo-url> /tmp/site-test && cd /tmp/site-test
      npm install && npm run build && cp .env.example .env && npm start

   done when · tick each as it passes

   • The site loads over https on your domain and the form appends a line to messages.log on the server
   • Someone who has never seen the repo follows the README from clone to a working site without asking a question
   • The README states which keys in content.json are required

   next phase