USWDS 3.0.0 Beta 4

[thisisdano]

What's new in 3.0.0 Beta 4

This release builds on Beta 3 and is up-to-date with USWDS 2.13.1.

This release is the second Sass Module release on the 3.0 Beta Branch.

• Updating package structure
• ⚠️ Starting with this Beta release, the uswds package is now publishing to the @uswds organization scope in npm, as @uswds/uswds

Note that there is no ZIP release with this beta. If you wish to use the Beta 4 release, you'll need to install it via npm.

---

Use package structure for all USWDS code. Reorganizes USWDS source code into a common package structure in a ./packages directory. Sass now uses common load paths to USWDS source packages (like @use "uswds-core") instead of relative paths (like @use "../../../uswds-core/src/styles"). Package structure and load paths will allow downstream users to more easily define, customize, and optimize their USWDS implementation and load individual component packages if desired.

⚠️ To work properly, the Sass compiler needs this package's packages directory as a load path, for instance by including something like includePaths: ["./node_modules/@uswds/uswds/packages"] as part of your gulp implementation of sass, or via sass-loader in webpack.

Gulp

.pipe(
  sass.sync(
    { includePaths: [ 
      "./node_modules/@uswds/uswds/packages"
     ]}
  )

Webpack

loader: "sass-loader",
options: {
  sassOptions: {
    includePaths: [
      "./node_modules/@uswds/uswds/packages"
    ],
  },
}

The most current Beta release of USWDS Compile is made for the USWDS 3.0 Beta. Check it out if you want to simplify compiling with USWDS 3.0.

Updating from stable or previous betas

Install on your project with npm install --save @uswds/uswds@beta

If you're using includePaths in Sass, you'll need to update the paths as shown above:

// OLD
.pipe(
  sass({
    includePaths: [
      `node_modules/uswds/scss`,
      `node_modules/uswds/scss/packages`,
    ],
  })
)

// NEW
.pipe(
  sass({
    includePaths: [
      `node_modules/@uswds/uswds/scss`,
      `node_modules/@uswds/uswds/packages`,
    ],
  })
)

⚠️ Breaking changes

From any Stable or Beta release

We changed the organization scope of our npm package and the file structure within the package. Teams need to update their project load paths (includePaths) to point to the new package and its stylesheets.

From Stable

Updated package names
Only affects those using USWDS packages. The required package is now called uswds-core and the global package is now uswds-global. The packages location is ./packages in this new release. If you use node_modules/@uswds/uswds/packages in your project's includePaths, you no longer need to prefix your package @includes (or @uses) with packages/.

For example:

@import 'packages/required';
@import 'packages/global';

Required and global SCSS packages have been updated to:

@import 'uswds-core';
@import 'uswds-global';

Security

0 vulnerabilities in regular dependencies (dependencies for USWDS projects installed with npm install uswds)

Internal only: 51 vulnerabilities (20 moderate, 31 high) in devDependencies (development dependencies)

Release ZIP SHA-256 hash: NO ZIP RELEASE WITH USWDS 3.0.0 BETA 4

---

This discussion was created from the release USWDS 3.0.0 Beta 4.

[mbucknell]

I had previously asked a question in #4452 about what had changed with initialization of components such as tooltips and modals with 3.0.0 Beta. It appears that there was some sort of change that has solved creating our own Vue USWDS component. Here is some context.

Until a few weeks ago we were using Vue 2.x but over the last few weeks I have converted one of our applications to use Vue 3.x. This also required a change in our javascript bundling tool since Vue 3 now recommends vite and no longer supports the rollup plugin required to compile single file components. I made the appropriate changes and everything was working but modals. Modal initialization was the issue and I believe it is related to using a virtual DOM and how the assets where bundled but effectively the code would raise errors somewhere deep in the bundled code and the modals would either not initialize, or not open, or not close. After much experimentation, I decided to try upgrading to USWDS 3.0 beta along with mounting our app components after DOM loading is complete solved all issues. in the modal components "mount" lifecycle hook when call modal.on(this.$el). I tried using the modal.off in the "beforeUnmount" lifecycle hook but it had not affect. I believe that this code does not clean up the component properly when passed the component's element. Instead I just remove using document.getElementById and passing the modal Id which removes the modal content. I am not convinced that cleans up everything that we need but so far we haven't had any issues.

I have not found any other issues with Beta 4. I have yet to play around with the custom style sheet building ... right now we just use the whole Sass style sheet. That's work for another day!

[mejiaj]

Hey @mbucknell! Sorry if we missed your question in a previous discussion.

I had previously asked a question in #4452 about what had changed with initialization of components such as tooltips and modals with 3.0.0 Beta

The original PR is a community contribution from @Swimburger and @MetroStar. It was created to improve component initialization in frameworks like React. We modified it a little so it would work with Beta for further testing.

[mbucknell]

No worries. I was trying the beta version out to see if it would fix a problem we where having with modal initialization and it does and I was very happy about that. I am eagerly awaiting version 3.0.0!