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.
- Open
brave://flags/#file-system-access-apiin a new browser tab. - Click Default (Disabled) next to File System Access API and select Enabled.
- 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:
- Open
http://localhost:[port]/admin/index.html. Replace[port]with the actual port number used by your development server. - Click “Work with Local Repository” and select the project’s root directory once prompted.
- 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):
- See if the produced changes (diff) look good.
- 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:
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 amis 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.lockfile. 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
.gitattributesare matched case-insensitively whencore.ignorecaseistrue. That’s the case in a repository cloned or created on macOS or Windows, so thereIMG_1234.JPGis 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 ifcommit.gpgsignis 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
.gitignorefiles or.git/info/excludeignore is saved but not committed, as withgit add. Your global ignore file, set withcore.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
.gitis 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 -Nand thefeature.manyFilesoption
- linked worktrees and submodules, where
- Fetching, pulling, pushing and switching branches still have to be done with a Git client.
- After the CMS commits, the next
git statusmay 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 statusorgit 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
localhostURL:- 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 uses4321, Eleventy uses8080, Hugo uses1313and Jekyll uses4000. - The
127.0.0.1and[::1]addresses can also be used instead oflocalhost. - If your CMS instance is not located under
/admin/, use the appropriate path. - It’s recommended to use
index.htmlin the URL to make sure the framework treats it as a static file. For example, usehttp://localhost:5173/admin/index.htmlinstead ofhttp://localhost:5173/admin/.
- 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
- 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 commitandgit 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.astrowith Astro or/src/routes/admin/+page.sveltewith 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.gitfolder exists.Unless Git commits are turned on, Sveltia CMS doesn’t read or write files inside the
.gitfolder. 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.