freesewing/markdown/dev/guides/v3/migration/en.md

title
V3 migration guide

This guide covers the migration from FreeSewing version 2 (v2) to FreeSewing version 3 (v3). It is intended for pattern designers and developers using our core library. But it is also a good source of information for anybody who wants to learn more about what's changed between v2 and v3 of FreeSewing.

The focus on this guide is on our core library, our designs, our monorepo, and other topics of interest to developers. It does not cover any changes to our website(s) or other more user-facing aspects.

Breaking changes

EMS only

FreeSewing is now ESM only. We no longer publish CJS modules.

To make this explicit, we now use .mjs as file extention for our source code.

Named exports only

All our published packages now have only named exports, and no longer any default exports.

Please refer to the reference documentation to see what named exports are available.

NodeJS 16 or more recent

FreeSewing now requires NodeJS version 16 or more recent.

This does not apply if you're using FreeSewing exclusively in the browser.

Removed packages

The following packages have been removed in v3:

• @freesewing/pattern-info
• gatsby-remark-jargon: We no longer use gatsby
• remark-jargon: Use rehype-jargon instead
• @freesewing/mui-theme: We no longer use Material-UI
• @freesewing/css-theme: We now use TailwindCSS
• @freesewing/components: These were depending on Material-UI and we no longer use it
• @freesewing/utils: We no longer use these, or they are included elsewhere
• @freesewing/plugin-export-dxf: DXF is kinda garbage, you deserve better
• @freesewing/plugin-validate

Migrating designs

Design configuration

In v2, a design had its own confifuration which contained all the info about the design. In v3, all of that is migrated to the part level. A design is now merely a container of parts, but also allows you to pass in additional data:

import { Design } from '@freesewing/core' // Note: named export
import { myPart1, myPart2 } from './parts.mjs'

export const MyDesign = new Design({
  parts: [ myPart1, myPart2 ],
  data: {
    anything: 'goes',
    this: {
      is: ['here', 'to', 'use' ]
    }
  }
})

You pass the Design contructor a single object where the only required property is the parts key that holds an array of part objects. The data property is optional, and allows you to add data/information to the design that you can use to facilitate frontend integration or a host of other things. Anything under data will be made available in the pattern store.

Obviously, we still need to know what measurements the design requires, what plugins it uses, what options it offers, and so on.

All of that is now configured at the part level.

Part configuration

In v3 of FreeSewing all configuration happens at the part level.

Refer to the part configuration docs for details on configuring parts.

Apart from being attached at the part level, changes in comparison to v2 include:

• The name property is mandatory in v3
• The dependencies property v2 is named after in v3
• The inject property in v2 is named from in v3
• The hide property in v2 is now one of hide, hideDependencies, or hideAll
• The plugins property is new

File and directory structure changes

• We no longer use a config folder, instead keep the config next to the parts.
• We use .mjs extentions rather than .js

This guide is a work in process