Skip to content
StudioCMS Docs
Main Site

Upgrade: 0.1.0-beta.31

StudioCMS 0.1.0-beta.31 introduces significant changes, including a new Kysely based database layer, a revamped plugin system, and various new features and improvements. This guide will help you upgrade your existing StudioCMS project to the latest version.

Breaking changes

Section titled “Breaking changes”
  • Refactored Plugin System. Please see the Plugin docs for more details.
  • Implemented new Kysely based database layer.
  • Removed support for config options directly passed to the StudioCMS astro integration, now all config options must be defined in studiocms.config.mjs file. Please see the Config Reference for more details.

New Features

Section titled “New Features”
  • Implemented new studiocms migrate command to handle database migrations.
  • Allow disabling Generator meta tags via features.dashboard.security.hideGeneratorTags config option.
  • StudioCMS now supports different database dialects via Kysely^.
  • Introduced new middleware to display system errors on pages with errors instead of crashing the entire site.
  • New plugin features:
    • Dynamic components and scripts injection to the dashboard via new plugin hooks.
    • New db helpers for easier database access within plugins.
  • Introduced new Dashboard page for managing the System management.
    • Includes a System info (debug) panel
    • Provides quick access to your database tables while in production.
  • Added the new developer toolbar app built-in to StudioCMS for viewing and managing your database while in development mode.
  • Integrated optional web-vitals/analytics tracking into the dashboard for better performance insights.
    • This can be enabled via the features.webVitals config option.
    • For those who previously used the @studiocms/web-vitals or @astrojs/web-vitals integrations, this is now built-in and can be configured via the StudioCMS config.

Bug Fixes & Improvements

Section titled “Bug Fixes & Improvements”
  • Updated ghost user image url.
  • Refactored page data urlRoute generation to resolve correctly.
  • Refactored and simplified dashboard layout components.
  • Improved StudioCMS config types and JSDoc comments.
  • Refactored CLI commands to use new database layer.
  • Introduced new debug utilities for easier access to helpful debug information.

Migration Steps

Section titled “Migration Steps”

To upgrade your StudioCMS project to version 0.1.0-beta.31, please follow these steps:

  1. Update your StudioCMS dependencies to the latest version:

    Terminal window
    npx @studiocms/upgrade

  2. If you have custom plugins, ensure they are updated to be compatible with the new plugin system. Refer to the Plugin docs for guidance.

  3. Review your studiocms.config.mjs file to ensure all configuration options are correctly set according to the new schema. Refer to the Config Reference for details.

    • Previously used @studiocms/web-vitals or @astrojs/web-vitals integrations? Remove them from your project dependencies and configure the built-in web vitals tracking via the features.webVitals option in your studiocms.config.mjs file:

      studiocms.config.mjs
      export default defineStudioCMSConfig({
        features: {
          webVitals: true,
        },
      });

  4. Setup a new database connection for the new Kysely based database layer. Update your .env file with the necessary database connection details. Keep your previous database intact for migration.

    Refer to the Database Setup Guide for more information on configuring your database.
    Refer to the Environment Variables Docs for more information on configuring your environment variables.

  5. Configure your database dialect in studiocms.config.mjs under the db option. For example, to use libSQL:

    studiocms.config.mjs
    export default defineStudioCMSConfig({
      db: {
        dialect: 'libsql', // or 'postgresql', 'mysql'
      },
    });

  6. Install the necessary database client packages for your chosen database dialect:

    Terminal window
    npm i @libsql/client @libsql/kysely-libsql

  7. Download the migration tool into the root of your StudioCMS project:

    Terminal window
    npm i @studiocms/migrator

    This tool will read your studiocms.config.mjs file to be able to connect to the correct database dialect.

  8. Running Schema Migrations:

    Since the database layer has changed, you will need to run migrations to update your database schema to be compatible with the new version. There is two ways to do this:

    Built into the StudioCMS CLI is a new migrate command that will run the necessary migrations for you. To use it, run the following command in your project directory:

    Terminal window
    npx studiocms migrate

    You will be prompted to select an option to, migrate your database schema to the latest version, rollback to a previous version, or view the current migration status. Select “Migrate to Latest” to update your database schema.

  9. Run the Migration Tool Web UI:

    Start the migration tool by running the following command in your project directory:

    Terminal window
    npx studiocms-migrator

    This will start a local web server. Open your browser and navigate to http://localhost:4321 to access the migration tool interface.

    This interface will give you options to migrate your database schema, as well as migrating your data from your old database to the new one.

  10. Once the migration is complete, start your StudioCMS project as usual:

    Terminal window
    npm run dev

    Your project should now be running with the updated database schema and configuration.

Final Notes

Section titled “Final Notes”
  • Ensure you have backups of your database before performing migrations.
  • Test your application thoroughly after the migration to catch any issues early.
  • Refer to the StudioCMS documentation for more information on new features and changes.
  • If you encounter any issues during the migration process, please reach out on our Discord community^, or open an issue on our GitHub repository^.