automatic deployment to neocities using

a how to on deploying static files to neocities using, most applicable for something built using @11ty.js

since the cli tool provided by neocities wasn't really built for managing multiple sites, i got kind of fed up with having to log out and reauth every time before uploading.

and since ive recently started using as my git hosting service, i decided i'd give making an autodeploy service so my website updated automatically when i push changes.

i used a couple tools to accomplish this including:

  • nodejs and npm
  • 11ty.js (the static site generator i use for this page)
  • the neocities npm package, which provides convenient access to the neocites api

Site Setup Details

the details of how i build static files aren't as important to this but i would refer you to the 11ty docs for more info on that! the important part is that my site is set up as an npm package, and the build command is npm run build which in turn executes npx @11ty/eleventy & sass styles:_site/styles and generates files that are placed in the _site directory.

after this, i run npm run deploy which runs this script:

const necoities = require('neocities')
const dotenv = require('dotenv')
const fs = require('fs')
const path = require('path')

const getAllFiles = function(dirPath, arrayOfFiles) {
  files = fs.readdirSync(dirPath)

  arrayOfFiles = arrayOfFiles || []

  files.forEach(function(file) {
    if (fs.statSync(dirPath + "/" + file).isDirectory()) {
      arrayOfFiles = getAllFiles(dirPath + "/" + file, arrayOfFiles)
    } else {
          path: path.join(__dirname, dirPath, "/", file),
          name: path.relative('./_site', path.join(__dirname, dirPath, "/", file))

  return arrayOfFiles

var siteFiles = getAllFiles("_site", [])



var api = new necoities(process.env.NEOCITIES_SITE, process.env.NEOCITIES_PW)

api.upload(siteFiles,(resp)  => {console.log(resp)})

this generates an array of the all files in the _site directory and passes them to the neocites api module.

the neocities api is initialized using the environment variables NEOCITIES_SITE and NEOCITIES_PW the easiest way to set these is with a .env file, whos contents will be added to the env by the dotenv module run by the deploy script

now on to the fun part ! :3

Build Process

i use for hosting and i thought id give their build system a try, and overall i really like it! its definitely easier to understand than githubs build manifests and works snapily!

the build manifest is read from a file called .build.yml placed in the root directory of the project, the one for this project looks like this:

image: alpine/latest
  - nodejs
  - npm
  -[your username]/[your repo name]
  - [replace with ssh key secret]
  - [replace with envfile secret]
  - setup: |
      cp envfile [your repo name]/.env
      cd [your repo name]
      npm install
  - build: |
      cd [your repo name] 
      npm run build
  - deploy: |
      cd [your repo name]
      npm run deploy

image is defined as alpine/latest, which should pull the newest version of alpine linux, and boot a vm the packages section takes care of installing nodejs and npm the sources define the repo to pull from the secrets provide the ssh keys for accessing the repo, and the envfile which contains the site name and password

(the .env file):

NEOCITIES_SITE="[site name]"
NEOCITIES_PW="[neocities password]"

the tasks list goes through the process of copying the .env file into the repo, installing the npm dependencies, building the files into the _site directory, and uploads the files to the neocities site provided in the env file.

(this was my first ever attempt at one of these but def lmk if u have any comments!)