Purging Unused Classes

ZoboUI is designed to generate a comprehensive range of styles based on your Theme Config, allowing you to experiment and design freely during development. However, when it comes to production, efficiency is key. You likely won't need every single class, and depending on your configuration, the USS file can become quite large. That's where ZoboUI's purging feature comes in handy.

Configuring Purging in the Theme Config Asset

To effectively set up purging for your project, follow these steps:

1. Access the Theme Config Asset: Open your Unity project and go to the ZoboUI Theme Config asset.
2. Navigate to the 'Compilation' Section: Here, you can configure how purging should work for your project.

Understanding the Configuration Fields

In the Compilation section, you will find several fields that allow you to fine-tune the purging process:

• Content:

  • Description: This field accepts paths, globs, or file patterns. It specifies the files ZoboUI should scan for used classes.
  • Default Values: By default, it includes "Assets/*.cs" and "Assets/*.uxml", covering C# scripts and UXML files in your Assets folder.
  • Usage: Tailor this field to include only the files where your UI classes are used, which helps in optimizing the purging process.

• Safelist:

  • Description: This field allows you to list classes that should always be included in the generated USS file.
  • Usage: Use this for classes not directly referenced in your project files but essential for your UI, such as those used in prefabs.

• Blocklist:

  • Description: Here, you can specify classes you want to exclude from the final USS file.
  • Usage: Useful for classes that might be referenced in your project but you wish to omit from the final stylesheet.

By carefully configuring these fields, you can ensure that the purging process aligns perfectly with your project's needs.

Generating the Purged USS File

Once you've set up your purging configurations, generating the purged USS file is a straightforward process. This final step is crucial for optimizing your project's performance by including only the necessary classes.

Steps to Generate the Purged File

1. Go to Your Theme Config Asset: Open your Unity project and navigate to the ZoboUI Theme Config asset.

2. Enter the Settings Section: Within the Theme Config asset, find and enter the 'Settings' section.

3. Locate the 'Purge' Button: In the 'USS Generation' subsection, you'll see the 'Purge' button. This is your gateway to creating an optimized USS file.

4. Configure the Output Path: Before you proceed, make sure to set the desired output path for your purged file. You can do this by updating the 'Purged File Path' field. Specify where you want the purged USS file to be saved in your project directory.

5. Initiate the Purging Process: Click the 'Purge' button to start the process. ZoboUI will then analyze your project based on your configurations and generate a USS file that includes only the classes actually used in your project.

This generated file will be smaller in size and more efficient, potentially leading to better performance in your final app or game. It's a crucial step in ensuring that your project is not only visually appealing but also optimized for performance.

Default Behavior

By default, ZoboUI looks through all .uxml and .cs files in your Assets folder to determine which classes are being used. For better performance and accuracy:

• Consider a Specific Folder for UI Files: We recommend creating a dedicated folder within your Assets for the UI files you use in production. This optimizes the purging process and minimizes false positives.

How Purging Works

Purging in ZoboUI is designed to search your project files for strings that match utility class names. This operation relies on the classes being statically analyzable within your code.

Avoid Dynamic Class Generation and String Concatenation

Dynamically generating class names can prevent the purging system from recognizing and retaining these classes. Let's look at an example:

This won't work (Dynamic Generation):

// Dynamic generation of a class name
string size = "sm";
string className = "text-" + size;

// Usage in code
myElement.AddToClassList(className);

In this example, the purging system will not identify "text-" + size as a valid class name due to its dynamic nature.

Recommended (Static Usage):

// Static class name
string className = "text-sm";

// Usage in code
myElement.AddToClassList(className);

Here, the class name is statically defined, making it easily recognizable by the purging system.

Using Safelist for Essential Classes

For classes that are essential but might not be directly referenced in your code (like those used in binary files, prefabs, or remote resources), you should use the safelist feature.

Example of Using Safelist:

In this case, even if my-class is not found directly in your scripts or UXML files, adding it to the safelist ensures it remains in the final purged USS file.

Custom Extractors

If the default extraction doesn't meet your specific needs, ZoboUI allows for the addition of custom extractors through plugins.

Reducing USS File Size Without Purging

If you're experiencing lag in the UI builder due to the file size or simply prefer not to purge, you have options:

• Prune Your Config: Remove colors or other values in the Config Asset that aren't being used frequently.
• Disable Unused Utilities: Within the Theme Config asset, you can toggle off utilities you're not using to further reduce the size of the generated USS file.

By carefully managing the classes in your USS file, you can ensure that your project remains efficient and responsive, without compromising on flexibility.