Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/apursley2012/neocities-dev/llms.txt

Use this file to discover all available pages before exploring further.

neocities-dev ships as a pre-built static site: the compiled JavaScript bundle, CSS, and HTML shells are all committed to the repository. There is no package.json or build step — cloning the repo gives you everything you need to serve or deploy the portfolio immediately.

​
Prerequisites

Make sure the following are installed before you begin:
  • Git — to clone the repository
  • A static file server for local preview (any option works — see below)
  • A code editor such as VS Code if you want to inspect or modify the source

​
Setup

1

Clone the repository

git clone https://github.com/apursley2012/neocities-dev.git
cd neocities-dev
After cloning you will see the full site already in place — index.html at the root, the compiled bundle at assets/main.js, compiled styles at assets/main.css, and the per-route HTML shells under pages/.
2

Preview locally with a static file server

Because the app uses ES modules and hash-based routing, you need to serve the files over HTTP rather than opening index.html directly in the browser. Any lightweight static server works:
npx serve .
Open http://localhost:3000 (or whichever port your server reports) in your browser. You should see the Y2K portfolio with the FakeBrowserChrome wrapper and FrameNav sidebar. Navigate between routes using the sidebar — all navigation happens via URL hash (/#/about, /#/projects, etc.) and requires no server involvement.
3

Deploy to Neocities

You have two options:Option A — Drag and drop (easiest)
  1. Log in to your Neocities dashboard.
  2. Drag the entire contents of the cloned folder (everything at the repo root) into the file upload area.
  3. Neocities will serve index.html at your site root, with the assets/, components/, pages/, and useScreenInit.js files alongside it.
Option B — Neocities CLI
# Install the CLI if you haven't already
npm install -g neocities

# Authenticate once
neocities login

# Push the repo contents
neocities push .
The CLI performs a diff upload — only changed files are sent, keeping deploys fast.

​
Deploying Elsewhere

Because neocities-dev is a pure static SPA that uses hash-based routing, it works on any static host with zero additional configuration:
HostNotes
GitHub PagesPush the repo contents to the gh-pages branch, or configure Pages to serve from the repository root.
NetlifyDrag-and-drop the repo folder in the Netlify dashboard, or connect the repo for automatic deploys.
VercelImport the repo — set the output directory to . (repository root) since there is no build step.
Any static hostUpload the repo root contents to the web root; no .htaccess or _redirects file needed.
Because all navigation happens via the URL hash (/#/, /#/about, etc.), the browser never requests a new path from the server. This means no 404-redirect rules are needed on any host — the hash is handled entirely client-side by React Router.
The pages/ directory contains a separate HTML shell for each route (e.g. pages/About.html, pages/Projects.html). Each shell loads the same assets/main.js bundle and sets window.__STATIC_PAGE_ROUTE__ to its own path value. These files exist so that Neocities can serve each route URL directly when a visitor lands on, say, yoursite.neocities.org/pages/About.html — the React app boots, reads __STATIC_PAGE_ROUTE__, and navigates to the correct hash route automatically.

Build docs developers (and LLMs) love

Get started for freeTalk to us