Bukwild Stylus Library

Common errors

• npm ERR! code ETARGET
  npm ERR! notarget No matching version found for stylus@^0.64.0

  cause The main `stylus` package (a peer dependency of this library) was temporarily removed or flagged from the npm registry, often due to security advisories, leading to installation failures.
  fix Check the `stylus` package's official npm page or GitHub repository for status updates. You might need to temporarily override the `stylus` version in your `package.json` to a known good one or use a GitHub reference if the npm registry version is unavailable.

• Error: `~bukwild-stylus-library/index.styl` not found

  cause Stylus cannot resolve the `@import` path to the `bukwild-stylus-library` package. This typically means the package is not correctly installed in `node_modules` or the Stylus compiler's `paths` option is not configured to include `node_modules`.
  fix Ensure `bukwild-stylus-library` is listed in your `package.json` and installed (`npm install` or `yarn install`). Verify your Stylus compiler configuration (e.g., in webpack, Gulp, or CLI) includes `node_modules` in its `paths` option for resolving `@import` statements starting with `~`.

• Stylus compilation error: 'fluid' is not defined

  cause The `fluid` mixin, or the main `index.styl` file containing it, was not successfully imported into the current Stylus file being compiled.
  fix Ensure that `@import "~bukwild-stylus-library/index.styl";` is present at the top of your main Stylus file or any file that requires the mixins. Also, verify that no syntax errors in the import path or the imported file itself are preventing successful loading.

Warnings

• breaking The default `fluid-default-max-break` variable, which dictates the upper breakpoint for the `fluid()` mixin's scaling, was changed from its previous value to 1440px. Projects relying on the old default will see altered responsive scaling behavior.
  Fix: If specific max-break behavior is required, explicitly set the `fluid-default-max-break` variable in your Stylus project before importing the library, e.g., `fluid-default-max-break = 1200px`.
• gotcha Stylus relies on a peer dependency of the `stylus` package itself. There have been instances where the core `stylus` package was temporarily unavailable or flagged in the npm registry due to unrelated malicious packages published by a maintainer's compromised account. While resolved, such incidents can cause installation failures.
  Fix: Always ensure your `stylus` peer dependency is correctly installed. If encountering `npm ERR! code ETARGET` or similar during `npm install`, check for recent advisories regarding the main `stylus` package on npmjs.com or GitHub and consider temporary workarounds like using a specific version from the GitHub repository if the npm package is affected.
• gotcha Stylus mixins, especially those with many arguments or optional parameters, can be prone to incorrect invocation syntax, leading to silent failures or unexpected CSS output. Stylus's transparent mixin behavior can sometimes cause ambiguity.
  Fix: Always refer to the library's examples for correct mixin usage. For `fluid()`, ensure property name comes first, followed by values, and then optional named arguments (`min-break: value`). Avoid using CSS property names as mixin names to prevent 'transparent mixin' conflicts.

Install

• npm install bukwild-stylus-library npm
• yarn add bukwild-stylus-library yarn
• pnpm add bukwild-stylus-library pnpm

Imports

• index.styl (main entry)
  wrong:

  import { fluid } from 'bukwild-stylus-library'

  correct:

  @import "~bukwild-stylus-library/index.styl"

  This package provides Stylus mixins and functions, which are imported directly within your .styl files using Stylus's `@import` syntax. The `~` prefix typically resolves paths from `node_modules`. Do not use JavaScript `import` statements.
• fluid (mixin)
  wrong:

  .selector
    fluid(padding: 20px, 10px)

  correct:

  .selector
    fluid padding, 20, 10, min-break: 768px

  Mixins like `fluid` are available globally once `index.styl` is imported. They are invoked directly within Stylus selectors. Ensure correct argument order and named parameters for options.
• boilerplate.styl
  wrong:

  @import "boilerplate"

  correct:

  @import "~bukwild-stylus-library/boilerplate.styl"

  The `boilerplate.styl` file, containing global Bukwild conventions, can be imported separately if only specific conventions are desired or if `index.styl` is not used. Ensure the full path including `~` is used for correct module resolution.

Quickstart

This quickstart demonstrates how to import the main Stylus library and utilize the `fluid()` mixin for responsive scaling of CSS properties and custom properties.

// my-project.styl
@import "~bukwild-stylus-library/index.styl";

// Define some base variables if needed, otherwise library defaults apply
// fluid-default-max-break = 1440px // Default in v3.0.0+
// fluid-default-min-break = 375px

.my-responsive-element
  font-size: 16px;
  // Scales padding from 20px (at 1440px viewport) down to 10px (at 375px viewport)
  fluid padding, 20, 10;

.my-custom-breakpoint-element
  margin-top: 50px;
  // Scales margin-top from 30px (at 1024px viewport) down to 15px (at 768px viewport)
  fluid(margin-top, 30, 15, min-break: 768px, max-break: 1024px);

// Using fluid with CSS custom properties (variables)
:root
  fluid(--site-padding, 40, 20); // Scale a custom property

.header
  padding: var(--site-padding);
  background: lightblue;

.footer
  padding: calc(var(--site-padding) / 2);
  background: lightgray;