Upgrades

Learn how to smoothly upgrade from one version to the next.

General instructions

Before you begin:

Backup your database
Carefully read the Changelog, especially the entries marked with: "BREAKING CHANGE"

Nitropage versions are managed via the package.json file in your project folder. Make sure to update the versions of all related dependencies. To automatically update just the Nitropage dependencies to their latest versions, run the following command:

pnpm up -L nitropage "@npio/*"
pnpm up -L @solidjs/meta @solidjs/router 
# or
npm install -D nitropage@latest @npio/cli@latest @npio/server@latest

Alternatively you can also run pnpm up, to update all dependencies of your project.

Afterwards you should apply database schema changes by running:

pnpm prisma generate
pnpm np update -m
# or
npm exec prisma generate
npm exec np update -m

Updating the 'src' folder

If you didn't make any changes to your projects src folder, you can run the following command, which will update the whole folder including all blueprints, styles, configs, etc.

WARNING: Make sure that your project is fully versioned before running the commands below, otherwise you risk loosing data!

NP_REPO_URL=https://codeberg.org/nitropage/nitropage
NP_STARTER=$NP_REPO_URL/packages/starter
NP_STARTER_RAW=$NP_REPO_URL/raw/branch/master/packages/starter

npx tiged -f $NP_STARTER/src#master src

Updating blueprints

The starter kit comes with several blueprints that are in your control, allowing you to change their code, functionality and appearance. On the other hand, if you leave their code as is, you can easily update them to the latest state:

WARNING: Make sure that your project is fully versioned before running the commands below, otherwise you risk loosing data!

NP_REPO_URL=https://codeberg.org/nitropage/nitropage
NP_STARTER=$NP_REPO_URL/packages/starter
NP_STARTER_RAW=$NP_REPO_URL/raw/branch/master/packages/starter

npx tiged -f $NP_STARTER/src/blueprints#master src/blueprints
npx tiged -f $NP_STARTER/src/components#master src/components

curl $NP_STARTER_RAW/src/app.css > src/app.css

Keep in mind that this doesn't delete any old files and doesn't take care of file renamings, that might have occured in newer starter kit versions. E.g. if a blueprint was renamed from faq.np.tsx to accordion.np.tsx, you have to manually delete the old faq.np.tsx file.

v0.65

1. Remove 'package.json' overrides

The overrides previously needed for vite can be removed again 🎉.

2. Update dependencies and install new ones

A major part of this version is the migration from Tailwind v3 to v4. This means that you have to add and remove a few dependencies.

Run the following commands or get a fresh copy of the package.json from the starter kit:

pnpm update -L
pnpm install -D @tailwindcss/vite
pnpm remove autoprefixer postcss
# or
npx npm-check-updates
npm install -D @tailwindcss/vite
npm remove autoprefixer postcss

3. Update 'app.config.ts'

Run the following commands or get a fresh copy of the app.config.ts from the starter kit:

NP_REPO_URL=https://codeberg.org/nitropage/nitropage
NP_STARTER=$NP_REPO_URL/packages/starter
NP_STARTER_RAW=$NP_REPO_URL/raw/branch/master/packages/starter

curl $NP_STARTER_RAW/app.config.ts > app.config.ts

4. Remove 'postcss.config.cjs' and 'tailwind.config.cjs' files

Both files are no longer needed with Tailwind CSS 4.0.

WARNING If you customized your project, make sure to read the Tailwind Upgrade Guide and manually apply the breaking changes to your code, before deleting these files.

rm postcss.config.cjs tailwind.config.cjs

v0.62

1. Update all dependencies

It's recommended to update all dependencies of your project. As a comparison check out the dependencies and devDependencies entries of the starter kit.

2. Add 'package.json' overrides

Starting with vinxi v0.5, your package.json must include the following entries, as a temporary workaround for an upstream issue:

"overrides": {
  "vite": "^5.4.11"
},
"pnpm": {
  "overrides": {
    "vite": "^5.4.11"
  }
}

3. Update 'src/routes'

The files in src/routes have to be updated. You can skip this, if you already have updated the whole src folder in the Updating the 'src' folder step. Otherwise run the following command:

NP_REPO_URL=https://codeberg.org/nitropage/nitropage
NP_STARTER=$NP_REPO_URL/packages/starter
NP_STARTER_RAW=$NP_REPO_URL/raw/branch/master/packages/starter

npx tiged -f $NP_STARTER/src/routes#master src/routes

v0.59

This version includes extensive changes in the internal architecture of Nitropage, which also asked for a complete rework of the starter kit structure. Learn more about the changes in the Nitropage v0.59 prerelease announcement.

Updating existing <0.59 projects in-place to v0.59 is not recommended. Instead generate a fresh starter project and move needed files from the old project to the new one. Please backup your project before you continue!

These commands will move the files from your old project to a new one. Please adjust them for your specific needs:

# Moving db related files
mv old-project/prisma/migrations new-project/prisma/
mv old-project/prisma/dev.db new-project/.data/

# Moving the storage folders
mv old-project/public/media new-project/.data/storage/public/
mv old-project/public/fonts new-project/.data/storage/public/

# Cleaning up obsolete cache folders
rm -r new-project/.data/storage/public/media/cache
rm -r new-project/.data/storage/public/media/min

# Moving the .git versioning folder
mv old-project/.git new-project/

Afterwards copy atleast the following variables from the old .env file to the new one:

NP_AUTH_SALT
NP_AUTH_IRON_PASSWORD renamed to NP_AUTH_PASSWORD

Last but not least, you should apply the database schema changes:

pnpm np update -m
# or
npm exec np update -m