Local Workflow

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

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, SvelteKit) 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, because this feature relies on the File System Access API, which is only supported by Chromium-based browsers at this time.

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 repository 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. 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 doesn’t perform any Git operations, so it doesn’t matter if the repository actually exists or not. However, the backend configuration is still used to store data in the browser’s IndexedDB, which is partitioned by the backend name and repo. For this purpose, you can use a dummy name, such as my-name/travel-blog.

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 your 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.

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 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

• 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 the hidden .git folder exists. While Sveltia CMS doesn’t read/write files inside the .git folder, it checks for the presence of the .git folder to verify that the selected folder is the project root and make sure changes made in the CMS can be tracked by Git.
• 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

The local repository support in Sveltia CMS doesn’t perform any Git operations. You have to manually fetch, pull, commit and push all changes using a Git client. Additionally, you’ll need to reload the CMS after modifying the configuration file or retrieving remote updates.

Future Plans

We will explore possibilities to add built-in Git operations in the CMS itself, possibly by integrating isomorphic-git, to enable committing changes directly from the CMS interface. The Netlify/Decap CMS proxy server actually has an experimental, undocumented Git mode that create commits locally. For more details, see discussion #31.

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