12 releases (5 breaking)
0.6.1 | Aug 7, 2023 |
---|---|
0.5.0 | Jul 31, 2023 |
#150 in WebAssembly
297 downloads per month
16KB
turf ðą
Warning | As of 0.4.0, the minimum supported Rust version is 1.70.0 by default! This can be circumvented by using the
once_cell
feature flag, which will lower the minimum supported version to 1.64.0.
turf
allows you to build SCSS to CSS during compile time and inject those styles into your binary.
Features
turf will:
- ðŋ transform your SCSS files into CSS with grass, right at compilation time
- ðŠī generate unique and dynamic class names for your CSS during compilation
- ðŽ minify and optimize your CSS using lightningcss, ensuring compatibility with various browser targets
- ðĻ inject the generated CSS into your binary, guaranteeing quick access to your styles whenever you need them
Usage
For a complete runnable example project, you can check out one of the examples:
leptos-example | yew-example | dioxus-example |
---|
1. Create SCSS styles for your application
// file at scss/file/path.scss
.TopLevelClass {
color: red;
.SomeClass {
color: blue;
}
}
2. Use the style_sheet
macro to include the resulting CSS in your code
turf::style_sheet!("scss/file/path.scss");
The macro from the above example will expand to the following code:
static STYLE_SHEET: &'static str = "<style_sheet>";
struct ClassName;
impl ClassName {
pub const TOP_LEVEL_CLASS: &'static str = "<unique_class_name>";
pub const SOME_CLASS: &'static str = "<another_unique_class_name>";
}
To access the generated class names, use the ClassName
struct and its associated constants:
let top_level_class_name = ClassName::TOP_LEVEL_CLASS;
let some_class_name = ClassName::SOME_CLASS;
3. Configuration
The configuration for turf can be specified in the Cargo.toml file using the [package.metadata.turf]
and [package.metadata.turf-dev]
keys. This allows you to conveniently manage your SCSS compilation settings for both development and production builds within your project's manifest.
Both profiles offer the exact same configuration options. However, if you haven't specified a [package.metadata.turf-dev]
profile, the [package.metadata.turf]
settings will also be applied to debug builds. This ensures consistency in the compilation process across different build types unless you explicitly define a separate configuration for the development profile.
Example configuration:
[package.metadata.turf]
minify = true
load_paths = ["path/to/scss/files", "path/to/other/scss/files"]
class_name_template = "custom-<id>-<original_name>"
[package.metadata.turf.browser_targets]
chrome = [80, 1, 2]
firefox = 65
safari = [12, 3]
The following configuration options are available:
-
minify
(default:true
): Specifies whether the generated CSS should be minified or not. If set to true, the CSS output will be compressed and optimized for reduced file size. If set to false, the CSS output will be formatted with indentation and line breaks for improved readability. -
load_paths
: Specifies additional paths to search for SCSS files to include during compilation. It accepts a list of string values, where each value represents a directory path to be included. This option allows you to import SCSS files from multiple directories. -
browser_targets
: Defines the target browser versions for compatibility when generating CSS. It expects a structure that includes specific versions for different browsers. Each browser can have its own version specified. -
class_name_template
(default:"class-<id>"
): Specifies the template for generating randomized CSS class names. The template can include placeholders to customize the output.<id>
will be replaced with a unique identifier for each CSS class name and<original_name>
will be replaced with the original class name from the SCSS file. -
debug
(default:false
): When set to true, this option will enable debug output of the read configuration and the generated CSS class names. This can be helpful for troubleshooting and understanding how the CSS is being generated.
3.1 Browser Versions
The available browsers are as follows:
- android
- chrome
- edge
- firefox
- ie
- ios_saf
- opera
- safari
- samsung
3.2 Browser Version Format
Three formats are supported:
major | major.minor | major.minor.patch |
---|---|---|
Use a single integer to specify the major version number. | Use an array [major, minor] to specify both the major and minor version numbers. |
Use an array [major, minor, patch] to specify the major, minor, and patch version numbers. |
Example: 1 or [1] represent version 1.0.0 |
Example: [1, 2] represents version 1.2.0 |
Example: [1, 2, 3] represents version 1.2.3 . |
Contributions
Contributions to turf are always welcome! Whether you have ideas for new features or improvements, don't hesitate to open an issue or submit a pull request. ðĪ
License
turf is licensed under the MIT license. For more details, please refer to the LICENSE file. ð
Dependencies
~13MB
~198K SLoC