Skip to main content

Getting started on Windows

warning

Official support for FreeSewing is provided for Linux, Mac, and BSD-based operating systems. This Getting started on Windows tutorial was written by FreeSewing community members and should be considered unofficial. However, if you encounter issues with this tutorial or require assistance with other Microsoft Windows issues, please feel free to ask for help and our community members will be happy to assist you!

You will first need to set up your development system either using Windows Subsystem for Linux or directly in Windows. Then, you can setup and start the FreeSewing development environment.

Setting up a development environment using Windows Subsystem for Linux (WSL) and Visual Studio Code (VSCode)​

If you already have a working WSL environment and VSCode Remote configured you can follow the getting started on Linux guide or skip ahead to Setting up the FreeSewing development environment (WSL). If not, the following process is very similar but has some differences to avoid quirks specific to this environment.

Windows Subsystem for Linux allows you to run a Linux distribution as a development environment, with enough functionality to develop a FreeSewing pattern. While this approach offers some advantages this is not strictly necessary to develop patterns on Windows. If you would prefer a simpler setup process refer to Setting up a development environment in Windows.

Installing and using an IDE is optional, you can skip that step or use a different editor if you'd like. This guide suggests VSCode as it is freely available on multiple platforms and provides enough functionality to build the FreeSewing project.

Install WSL​

warning

This guide uses WSL version 2, which requires installing the Hyper-V virtualisation system. If you have another virtualisation system installed (such as VirtualBox or VMWare) you may run into conflicts which require either updating that system to a version which can use the HyperV backend or porting your existing machines to use HyperV.

Follow the Windows Subsystem for Linux Installation Guide for Windows 10 (requires a recent version of Windows 10).

Install NVM​

Open a new WSL terminal from the shortcuts created or by searching for "WSL Terminal" in the start menu. Install NVM by following the NVM setup guide. Once installed you will need to activate NVM by either following the instructions printed to the screen or opening a new terminal.

Install Node.js (and optionally Yarn)​

Now that you have NVM installed, you can install Node.js. The latest version can be installed using nvm install default. You can also install a specific version using nvm install v18.17.0. For the purposes of debugging it can be useful to have the same version of Node.js installed as the main project uses, which you can then activate using nvm use <version>. You can determine what version the FreeSewing project uses by checking freesewing/freesewing/.nvmrc.

warning

At the time this guide was written the latest version of Node.js/npm has a bug in the dependency resolution process which causes the freesewing project to fail to build. Use the latest LTS version (currently 18.17.0) or the specific version used by the main project to avoid this issue.

Node.js comes with the Node Package Manager (npm) by default which can be used to set up the project. The default package manager uses a fairly simplistic approach to dependency resolution which can make builds take a long time. Yarn is an alternative package manager which makes builds faster, especially for monolithic projects like FreeSewing. If you'd like to install yarn run npm install yarn --global (optional, but recommended).

The create-freesewing-pattern script will attempt to create a git repository as part of the setup. It's not strictly required to have git installed in the WSL environment but you will get errors during the project setup process if it isn't installed or configured correctly. As such it's recommended to have git installed on the WSL environment even if you're going to be using a GUI client from the windows side.

sudo apt install git
git config --global user.email "<the email address you use for your git account>"
git config --global user.name "<your display name for your git account>"

Install VSCode (optional)​

Download and install VSCode.

note

FreeSewing uses .editorconfig files to enforce a consistent style for the project. VSCode relies on extensions to provide this functionality and due to a design shortcoming it does not respect certain editorconfig options which will break certain files in the freesewing project (see vscode/65663 for details). If you use this editor please ensure that your settings.json file is configured to not trim trailing whitespace from Markdown files. The following snippet can be added to your settings.json file to add an exemption for this file type:

  "[markdown]": { "files.trimTrailingWhitespace": false },

Install VSCode Remote​

In order to be able to use VSCode's IDE features (such as the built in terminal) and also make use of the Node.js installation we set up in the previous steps you will need to install VSCode Remote so that VSCode can make use of the Linux environment. Follow the getting started guide for VSCode Remote (If you've been following this guide you have already done steps 1 and 2, you will only need to install the remote development extension)

Setting up a development environment in Windows.​

Install NVM​

While Node.js can be installed directly on Windows, we strongly recommend using a version manager such as Node Version Manager for Windows. That link will take you to the latest release which provides an installer you can download and run. Once nvm-windows is installed you will be able to continue with the rest of this process.

Install Node.js (and optionally Yarn)​

Open a Powershell terminal or command prompt. Run nvm ls available to show versions that can be installed. Choose the appropriate version (you should use the same version as the freesewing project or latest LTS version) then run nvm install 18.17.0 and nvm use 18.17.0 (where 18.17.0 is the full version string of the version you wish to use) to activate the newly installed version. You will receive a prompt for elevated permissions and will need to accept it in order to activate the new version of Node.js.

warning

At the time this guide was written the latest version of Node.js/npm has a bug in the dependency resolution process which causes the freesewing project to fail to build. Use the latest LTS version (currently 18.17.0) or the specific version used by the main project to avoid this issue.

Node.js comes with the Node Package Manager (npm) by default which can be used to set up the project. The default package manager uses a fairly simplistic approach to dependency resolution which can make builds take a long time. Yarn is an alternative package manager which makes builds faster, especially for monolithic projects like FreeSewing. If you'd like to install yarn run (npm install yarn -g) (optional).

Setting up the FreeSewing development environment​

In VSCode or in a terminal, navigate to the folder you wish to contain your new patterns (e.g. D:\Documents\my-freesewing-patterns). Inside this directory run npx @freesewing/new-design.

After you've answered some questions, it will take a while to set everything up. When it's done, you will have a new folder with the development environment inside.

tip

The folder will have the name you chose above.

note

Questions​

What template to use​

Use From scratch unless you want to start from our of our blocks:

  • Use Extend Brian to start from Brian
  • Use Extend Bent to start from Bent
  • Use Extend Bella to start from Bella
  • Use Extend Breanna to start from Breanna
  • Use Extend Titan to start from Titan

What name to use​

This will become the name of your design. Stick to [a-z] here to avoid problems.

If you're not certain what to pick, just mash some keys, it doesn't matter.

What package manager to use​

You may wish to choose yarn since that is the package manager that we use when doing work in the monorepo, and many of our tutorials are written to use yarn. However, it doesn't really matter. You can choose either yarn or npm as you wish.

Start the development environment​

You will have a new folder that has the name you picked for your design. If you chose test, you will have a folder named test. If you chose banana, you'll have a folder named banana. (Within this new folder, the design subfolder holds your design's configuration file and source code. You can ignore all other subfolders and files; they are part of the development environment.)

To start the development environment, navigate to the folder that was created and run yarn dev (or npm run dev if you're using npm as a package manager).

Then open your browser and go to http://localhost:8000

tip

The development environment will watch for any changes you make to the pattern's source code or configuration. When you do, it will update automatically in your browser.

note
Yay, you're done!​

All you have to do now is design your pattern. Thankfully, we have a tutorial for that too: