Static sites

A static site is a folder of HTML, CSS, JavaScript and images, either built by a tool such as Vite or Astro or committed as-is. HCode serves that folder with its own file server, so you don't need a start command or a web server of your own.

#When HCode serves your site as files

An automatic build is served as a static site when:

• the build produced static output, as Vite, Create React App and static Astro builds do;
• the repository is plain HTML with an index.html;
• the start command only previews or serves the output, such as vite preview, astro preview, npx serve dist or http-server. HCode replaces it with its own file server.

A start command that runs your own server is used as it is. Background workers are never static sites, and a Dockerfile build always runs your image's own command. For Django, FastAPI and Flask repositories, HCode marks the project as a server when you create it from GitHub, so a stray build/index.html doesn't turn it into a static site.

#The output directory

Output directory under Settings is the folder your build writes to, such as dist, build or out. Leave it empty and HCode finds the folder holding index.html, preferring generated output (dist/public, dist, build, out, site) over public and the repository root.

If your setting points at a folder without the site, HCode serves the right one and the deployment says so: "Static output auto-corrected: serving dist instead of public". The setting itself is only updated when it was empty or looked platform-generated. When nothing needed correcting, the deployment notes "Static runtime detected: serving dist".

#Don't set a start command

A static build has no node binary, so a start command such as node index.js stops the container from starting. Start command (optional) warns about this under the field; leave it empty for a static site.

#How files are served

• A request for a file returns it; a request for a folder returns its index.html.
• A path with no file extension that matches no file returns your root index.html, so client-side routing in a single-page app works.
• A missing file with an extension, such as /logo.png, returns 404 "Not Found".
• Only GET and HEAD are answered.

The site listens on the project's port, 80 unless you set another. Its filesystem is read-only apart from a 64 MiB /tmp.

#When a static deploy fails

During a deploy, HCode requests the site's root page and one of the assets it links to, and checks what comes back. These are the failures it names, with the code shown on the failed deployment:

The folder and asset names in the messages are your own. For other problems, see Build failures and App won't start.