Skip to content

Commit

Permalink
Merge pull request #103 from mdmower-csnw/csnw-sourcemaps
Browse files Browse the repository at this point in the history 
USWDS-Compile - Gulp: Support disabling sass sourcemaps
  • Loading branch information
@heymatthenry
heymatthenry authored Jul 17, 2024
2 parents c2db086 + 77305e5 commit d558a0e
Show file tree
Hide file tree
Showing 4 changed files with 33 additions and 376 deletions.
41 changes: 24 additions & 17 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,22 +78,29 @@ USWDS is changing its file structure and package naming convention starting with

Use path settings to customize where USWDS Compile looks for USWDS source and outputs processed files. **The value of the default may depend on the USWDS version you've defined in `settings.version`.** When applicable, the relevant value of `settings.version` precedes the default.

| Setting | Default | Description |
| ------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paths.src.uswds` | `2`: `"./node_modules/uswds/dist"`<br />`3`: `"./node_modules/@uswds"` | Source location of the `uswds` package |
| `paths.src.sass` | `2`: `"./node_modules/uswds/dist/scss"`<br />`3`: `"./node_modules/@uswds/uswds/packages"` | Source location of the USWDS Sass |
| `paths.src.theme` | `2`: `"./node_modules/uswds/dist/scss/theme"`<br />`3`: `"./node_modules/@uswds/uswds/dist/theme"` | Source location of the USWDS theme files (Sass entry point and starter settings files) |
| `paths.src.fonts` | `2`: `"./node_modules/uswds/dist/fonts"`<br />`3`: `"./node_modules/@uswds/uswds/dist/fonts"` | Source location of the USWDS fonts |
| `paths.src.img` | `2`: `"./node_modules/uswds/dist/img"`<br />`3`: `"./node_modules/@uswds/uswds/dist/img"` | Source location of the USWDS images |
| `paths.src.js` | `2`: `"./node_modules/uswds/dist/js"`<br />`3`: `"./node_modules/@uswds/uswds/dist/js"` | Source location of the USWDS compiled JavaScript files |
| `paths.src.projectSass` | `"./sass"` | Source location of any existing project Sass files outside of `paths.dist.theme`. The `watch` script will watch this directory for changes. |
| `paths.src.projectIcons` | `""` | Source location of any additional project icons to include in the icon sprite. (Use _only_ these project icons in the sprite by setting `sprite.projectIconsOnly` to `true`.) |
| `paths.dist.theme` | `"./sass"` | Project destination for theme files (Sass entry point and settings) |
| `paths.dist.img` | `"./assets/uswds/images"` | Project destination for images |
| `paths.dist.fonts` | `"./assets/uswds/fonts"` | Project destination for fonts |
| `paths.dist.js` | `"./assets/uswds/js"` | Project destination for compiled JavaScript |
| `paths.dist.css` | `"./assets/uswds/css"` | Project destination for compiled CSS |
| `sprite.projectIconsOnly` | `false` | Include _only_ the icons in `paths.src.projectIcons` in the icon sprite. |
| Setting | Default | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paths.src.uswds` | `2`: `"./node_modules/uswds/dist"`<br />`3`: `"./node_modules/@uswds"` | Source location of the `uswds` package |
| `paths.src.sass` | `2`: `"./node_modules/uswds/dist/scss"`<br />`3`: `"./node_modules/@uswds/uswds/packages"` | Source location of the USWDS Sass |
| `paths.src.theme` | `2`: `"./node_modules/uswds/dist/scss/theme"`<br />`3`: `"./node_modules/@uswds/uswds/dist/theme"` | Source location of the USWDS theme files (Sass entry point and starter settings files) |
| `paths.src.fonts` | `2`: `"./node_modules/uswds/dist/fonts"`<br />`3`: `"./node_modules/@uswds/uswds/dist/fonts"` | Source location of the USWDS fonts |
| `paths.src.img` | `2`: `"./node_modules/uswds/dist/img"`<br />`3`: `"./node_modules/@uswds/uswds/dist/img"` | Source location of the USWDS images |
| `paths.src.js` | `2`: `"./node_modules/uswds/dist/js"`<br />`3`: `"./node_modules/@uswds/uswds/dist/js"` | Source location of the USWDS compiled JavaScript files |
| `paths.src.projectSass` | `"./sass"` | Source location of any existing project Sass files outside of `paths.dist.theme`. The `watch` script will watch this directory for changes. |
| `paths.src.projectIcons` | `""` | Source location of any additional project icons to include in the icon sprite. (Use _only_ these project icons in the sprite by setting `sprite.projectIconsOnly` to `true`.) |
| `paths.dist.theme` | `"./sass"` | Project destination for theme files (Sass entry point and settings) |
| `paths.dist.img` | `"./assets/uswds/images"` | Project destination for images |
| `paths.dist.fonts` | `"./assets/uswds/fonts"` | Project destination for fonts |
| `paths.dist.js` | `"./assets/uswds/js"` | Project destination for compiled JavaScript |
| `paths.dist.css` | `"./assets/uswds/css"` | Project destination for compiled CSS |

### Additional settings

| Setting | Default | Description |
| --------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sprite.projectIconsOnly` | `false` | Include _only_ the icons in `paths.src.projectIcons` in the icon sprite. |
| `settings.compile.browserslist` | `["> 2%", "last 2 versions", "IE 11", "not dead"]` | Define the [browserslist query](https://github.com/browserslist/browserslist?tab=readme-ov-file#queries) for CSS prefixes generated by [autoprefixer](https://github.com/postcss/autoprefixer). |
| `settings.compile.sassSourcemaps` | `true` | Include sourcemap when compiling SASS to CSS. |

### Functions

Expand Down Expand Up @@ -143,7 +150,7 @@ With that setup, you could do the following in the terminal:
### Usage tips

- **Use `init` only once.** The `init` task is meant for initializing the design system on a project. Since it will overwrite project files (like settings files and the Sass entry point), use it sparingly and don't use it for updating the design system on a project, or at any point after you've customized your settings files.
- **Stay up-to-date with USWDS with `updateUswds`.** When updating your project's version of USWDS, run the `npx gulp updateUswds` command to copy any updated USWDS assets into your project. Alternatively, you can run the `copyAssets` task. These tasks update USWDS static assets (like images, fonts, and compiled JavaScript) and will not override any of your project customizations. These actions might introduce breaking changes, so be sure to check out the related [USWDS releases notes](https://github.com/uswds/uswds/releases) for any additional tasks that must be completed when updating to a new version of USWDS.
- **Stay up-to-date with USWDS with `updateUswds`.** When updating your project's version of USWDS, run the `npx gulp updateUswds` command to copy any updated USWDS assets into your project. Alternatively, you can run the `copyAssets` task. These tasks update USWDS static assets (like images, fonts, and compiled JavaScript) and will not override any of your project customizations. These actions might introduce breaking changes, so be sure to check out the related [USWDS releases notes](https://github.com/uswds/uswds/releases) for any additional tasks that must be completed when updating to a new version of USWDS.
- **Compile only from a single Sass entry point.** Define the location of this entry point with `paths.dist.theme`. If you have project Sass files outside the `paths.dist.theme` directory, load these files into your single entry point via `@forward`, `@use`, or `@import`. To include these project Sass files in your `gulp watch` task, set `paths.src.projectSass` to your project Sass directory. The Sass will still compile from the single entry point located in `paths.dist.theme`.
- **Only check theme files and custom icons into version control.** You should have a build process that copies static assets like images, fonts, and compiled JavaScript from the `uswds` package. This assures that these assets are up-to-date with whatever version of USWDS you're using. You only need to track your customizations (like settings, theme files, custom icons, and your gulpfile) in version control.

Expand Down
14 changes: 9 additions & 5 deletions gulpfile.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@ const path = require("path");
const postcss = require("gulp-postcss");
const replace = require("gulp-replace");
const sass = require("gulp-sass")(require("sass-embedded"));
const sourcemaps = require("gulp-sourcemaps");
const del = require("del");
const svgSprite = require("gulp-svgstore");
const rename = require("gulp-rename");
Expand Down Expand Up @@ -66,6 +65,7 @@ let settings = {
},
},
browserslist: ["> 2%", "last 2 versions", "IE 11", "not dead"],
sassSourcemaps: true,
},
sprite: {
width: 24,
Expand Down Expand Up @@ -191,8 +191,9 @@ function buildSass() {
],
};

return src([`${paths.dist.theme}/*.scss`.replace("//", "/")])
.pipe(sourcemaps.init({ largeFile: true }))
return src([`${paths.dist.theme}/*.scss`.replace("//", "/")], {
sourcemaps: !!settings.compile.sassSourcemaps,
})
.pipe(
sass({
outputStyle: "compressed",
Expand All @@ -201,8 +202,11 @@ function buildSass() {
)
.pipe(replace(/\buswds @version\b/g, `based on uswds v${pkg}`))
.pipe(postcss(buildSettings.plugins))
.pipe(sourcemaps.write("."))
.pipe(dest(paths.dist.css));
.pipe(
dest(paths.dist.css, {
sourcemaps: settings.compile.sassSourcemaps ? "." : undefined,
})
);
}

function watchSass() {
Expand Down
Loading

0 comments on commit d558a0e

Please sign in to comment.