Skip to content

Local Development Workflow ​

Developers can smoothly work with local Git repositories using Sveltia CMS while running it on a local development server. This allows developers to test and edit content locally without needing to push changes to a remote repository first.

Breaking changes from Netlify/Decap CMS

Our local development workflow eliminates the need for a proxy server. For security and performance reasons, we don’t support netlify-cms-proxy-server or decap-server. The local_backend option is ignored. Read on to learn how to use the new, streamlined workflow.

Another Option: Test Backend

If you want to test the CMS but don’t want to modify local files, you can use the Test backend instead. It lets you connect to a virtual file system in the browser, so the CMS can be tested without affecting your local files.

Use Cases ​

  • Test Sveltia CMS locally before deploying it to a production environment.
  • Edit the CMS configuration and see how it affects the CMS behavior.
  • Make bulk changes to content files and assets and commit them at once.
  • Work offline without an internet connection.

Requirements ​

You must have a Git repository initialized in your project directory. You can create a new repository with git init or clone an existing one.

You also need to have a local development server running for your frontend framework (e.g. Astro, Eleventy, Hugo, Next.js) and have installed Sveltia CMS in the project.

You need Google Chrome, Microsoft Edge, Brave or any other Chromium-based browser. The workflow doesn’t work in Firefox, Safari or other non-Chromium browsers. It relies on the File System Access API, which only Chromium-based browsers support at this time.

Mozilla plans to implement the API in Firefox, but it’s not available yet. We track Firefox support in issue #38.

Enabling File System Access API in Brave ​

In the Brave browser, you must manually enable the File System Access API with an experiment flag to take advantage of the local development workflow.

  1. Open brave://flags/#file-system-access-api in a new browser tab.
  2. Click Default (Disabled) next to File System Access API and select Enabled.
  3. Relaunch the browser.

Configuration ​

In your CMS configuration, you must configure one of the supported Git backends: GitHub, GitLab or Gitea/Forgejo. No other configuration is required.

Authentication Not Required

If you plan to only work with your local repository, you don’t need to set up authentication with your Git backend. You can use the CMS as a local-only editor UI and commit changes manually using Git, or let the CMS commit them for you. However, if you want to edit content remotely as well, you must set up authentication as described in the backend documentation.

Repository Name Can Be Arbitrary

If you don’t have a remote repository yet, you can use any repository name for the repo property in the backend configuration. The CMS never connects to the remote repository in this workflow, so it doesn’t matter whether the repository exists.

The backend configuration is still used to store data in the browser’s IndexedDB, which is partitioned by the backend name and repo. A dummy name, such as my-name/travel-blog, works fine for this.

Workflow ​

The local workflow consists of four main steps:

1. Start the development server ​

Launch the local development server for your frontend framework, typically with npm run dev, pnpm dev or yarn dev.

2. Edit content ​

In any Chromium-based browser:

  1. Open http://localhost:[port]/admin/index.html. Replace [port] with the actual port number used by your development server.
  2. Click “Work with Local Repository” and select the project’s root directory once prompted.
  3. Edit content normally using the CMS. All changes are made to local files.

3. Preview changes ​

Open the dev site at http://localhost:[port]/ in any browser to preview the rendered pages. To make further edits, return to the CMS.

4. Commit changes ​

With any Git client (CUI or GUI):

  1. See if the produced changes (diff) look good.
  2. Commit and push the changes if satisfied, or discard them if you’re just testing.

If you turn on Git commits, the CMS commits each change for you, so you only need to review and push the commits.

Git Commits ​

By default, the CMS only saves your changes to the files, and you commit them yourself. If you turn on Git commits, the CMS also commits each save to the current branch of your local repository, the same way the Git backends commit to the remote repository.

To turn it on, open the Settings, select Developer and turn on Commit Changes to Git. The setting is stored in your browser, so it only applies to you. Below the switch, the CMS shows the branch and the author it will commit with, or why it can’t commit right now.

The commits use the same messages as with a Git backend, including any custom commit messages you have configured.

Only the files the CMS saves are committed. Other changes in your working tree, such as templates or styles you’re working on, are left out.

The commits stay on your computer until you push them with your Git client. They’re also recorded in the reflog, so you can find and undo them with Git as usual.

Setting Your Identity ​

The CMS can only read the configuration of the repository itself (.git/config), not your global Git configuration, which lives outside the project folder. Set your name and email address in the repository:

sh
git config --local user.name "Your Name"
git config --local user.email "[email protected]"

Note that git config user.name without a value only shows the name Git uses, which may come from your global configuration.

When Changes Aren’t Committed ​

In the following cases, the CMS saves your changes without committing them and tells you why. This keeps your own work in progress out of its commits.

The CMS doesn’t commit when:

  • You have other changes staged for commit. Commit or unstage them first. Changes you haven’t staged don’t get in the way.
  • A merge, rebase, cherry-pick, revert or git am is in progress, or some files have conflicts. The message tells you how to finish or cancel the operation.
  • Another Git process is using the repository, which is indicated by a .git/index.lock file. If no Git process is running, delete the file.
  • No branch is checked out (a detached HEAD).
  • Your name and email address aren’t set in the repository, as described above.
  • A saved file is tracked with Git LFS. As with Git, the patterns in .gitattributes are matched case-insensitively when core.ignorecase is true. That’s the case in a repository cloned or created on macOS or Windows, so there IMG_1234.JPG is caught by *.jpg.

While the CMS commits, it creates .git/index.lock like Git does, so Git commands that change the repository refuse to run until it’s done.

Caveats ​

The CMS commits in the browser with the help of isomorphic-git, rather than with Git itself. This brings some limitations:

  • Git hooks, such as pre-commit, are not run, and commits are not signed, even if commit.gpgsign is set.
  • Filters and attributes set in .gitattributes, such as line ending conversion, are not applied. Files tracked with Git LFS are saved but not committed.
  • A new file that the repository’s .gitignore files or .git/info/exclude ignore is saved but not committed, as with git add. Your global ignore file, set with core.excludesFile, is not read, so a file only it ignores is committed.
  • In the following repositories, changes are only saved, not committed:
    • linked worktrees and submodules, where .git is a file pointing outside the project folder
    • repositories using SHA-256 object names or the reftable format
    • repositories whose index is split, sparse or in version 3 or 4, which Git uses for sparse checkouts, git add -N and the feature.manyFiles option
  • Fetching, pulling, pushing and switching branches still have to be done with a Git client.
  • After the CMS commits, the next git status may take a moment longer than usual, as Git checks the committed files again.
  • Saving takes longer in a large repository, as the CMS reads the whole Git index every time. With tens of thousands of files, committing can add a fraction of a second to each save. The first save after a Git command that updates the index, such as git status or git pull, takes a little longer. The very first save also loads the Git library, which is about 50 KB.

Tips & Tricks ​

  • An indicator is displayed in the Account menu when using the local workflow.
  • The localhost URL:
    • The port number varies by framework. Check the terminal output from the previous step. For example, if you use Vite-based frameworks like SvelteKit or VitePress, the default port is 5173. Astro uses 4321, Eleventy uses 8080, Hugo uses 1313 and Jekyll uses 4000.
    • The 127.0.0.1 and [::1] addresses can also be used instead of localhost.
    • If your CMS instance is not located under /admin/, use the appropriate path.
    • It’s recommended to use index.html in the URL to make sure the framework treats it as a static file. For example, use http://localhost:5173/admin/index.html instead of http://localhost:5173/admin/.
  • Git clients:
    • You can use any Git client of your choice, including command-line tools (CUI) or graphical user interfaces (GUI).
    • For CUI, you can use the standard Git commands like git diff, git commit and git push.
    • For GUI, popular options include GitHub Desktop, Sourcetree, Tower and GitKraken. GitHub Desktop can be used for any repository, not just GitHub-hosted ones. VS Code also has built-in Git support.
  • Depending on your framework, you may need to manually rebuild your site or reload the page to reflect the changes you have made. Check your framework’s documentation for details.
  • You can skip the site preview check if your changes don’t involve any pages.

Troubleshooting ​

  • Load Sveltia CMS from a static HTML file in your site’s static files folder, such as /public/admin/index.html. Don’t load it from a page rendered by your framework, such as /src/pages/admin.astro with Astro or /src/routes/admin/+page.svelte with SvelteKit.

    While your local development server is running, such a page is reloaded every time a file changes. This can interrupt saving and leave a file empty or a temporary .sveltia-tmp-* file behind. Live reload is not applied to a static file.

    Sveltia CMS shows a warning at the top of the page if it detects this problem with a Vite-based framework, such as Astro, Nuxt, SvelteKit or VitePress.

  • If you get an error saying “not a repository root directory”, make sure you’ve turned the folder into a repository with either a CUI (git init) or GUI, and that the hidden .git folder exists.

    Unless Git commits are turned on, Sveltia CMS doesn’t read or write files inside the .git folder. It still checks that the folder exists, to verify that the selected folder is the project root and that Git can track the changes made in the CMS.

  • If you’re using Windows Subsystem for Linux (WSL), you may get an error saying “Can’t open this folder because it contains system files.” This is due to a limitation in the browser, and you can try some workarounds mentioned in this issue and this thread.

Limitations ​

Apart from committing your changes if you turn it on, Sveltia CMS doesn’t perform any Git operations with the local repository. You have to fetch, pull and push changes manually with a Git client, and commit them too unless the CMS does. Additionally, you’ll need to reload the CMS after modifying the configuration file or retrieving remote updates.

Future Plans

We plan to use the newly available File System Observer API to detect changes and eliminate the need for manual reloads.