PurgeTSS – Modern and Optimized Styling for Titanium Applications

Introduction

Developing mobile applications with Titanium SDK and the Alloy framework offers great flexibility and power. However, as projects grow, maintaining clean, efficient, and manageable style files (TSS) becomes a significant challenge. This is where PurgeTSS comes into play: an open-source toolkit meticulously designed to automate, optimize, and enhance style management in your Titanium projects.

What is PurgeTSS?

PurgeTSS is a command-line toolkit (CLI) that introduces modern style management to Titanium, inspired by the philosophy of Tailwind CSS:

Complete toolkit: All-in-one solution for style management in Titanium projects
Utility library: Over 21,000 predefined classes ready to use
Automatic purging: Generates an optimized app.tss file based on classes used in your XML files
Advanced customization: Configurable system of themes, colors, spacing, and JIT (Just-In-Time) classes
Integrated support: For popular icon fonts (Font Awesome, Material Icons, Material Symbols, Framework7)
Seamless integration: Runs automatically during the build process through Alloy.jmk
Animation module: 2D Matrix animations and transformations for UI elements
Grid system: Two-dimensional grid system to align and distribute elements

PurgeTSS in Detail

When developing mobile applications with Titanium, one of the biggest long-term challenges is maintaining a coherent and scalable styling system. PurgeTSS transforms this aspect of development, offering a revolutionary approach inspired by modern CSS frameworks.

A New Paradigm for Styles in Titanium

The magic of PurgeTSS begins with its “utility-first” approach. Instead of creating specific styles for each component, you work with an extensive library of utility classes that you can combine directly in your XML views. This approach not only accelerates development but also creates a consistent visual language throughout your application.

<View class="mx-2 h-64 w-screen rounded-lg bg-blue-500">
  <Label class="text-xl font-bold text-white">Hello World</Label>
</View>

With the code above, you've defined a view with full width, specific height, blue background, and rounded corners—all without writing a single line of TSS. And the best part is that PurgeTSS will automatically analyze your XML files and generate only the necessary TSS code in the app.tss file, keeping your view-specific .tss files intact.

Automatic Optimization: Less is More

During each build, PurgeTSS analyzes your XML files to identify which classes you're actually using. With this information, it generates an optimized app.tss file that contains exclusively the necessary styles. The result: smaller files, faster builds, and improved runtime performance.

This intelligent “purging” means you can have access to thousands of utilities without worrying about the final code size. Your view-specific TSS files remain intact, allowing you to combine both approaches as needed.

Centralized Customization

One of the most powerful aspects of PurgeTSS is its customization capability through a single configuration file. In purgetss/config.js you can define:

Your custom color palette
Specific spacing values for your design
Custom typography and font sizes
Your own utility classes or override existing ones
JIT (Just-In-Time) classes with arbitrary values directly in your views

This centralized approach greatly simplifies maintenance and design consistency, especially in large teams or long-term projects.

Tools That Enhance Workflow

PurgeTSS goes beyond style generation, offering tools that enhance your entire development process:

VSCode integration: Generates definition files for intelligent autocompletion of classes in your XML files
Icon support: Specific commands to add and manage popular icon fonts like Font Awesome, Material Icons, and Material Symbols
“shades” command: Generates custom color variations from hexadecimal colors
Animation module: Implements 2D Matrix animations and transformations with a simple and declarative syntax
Grid system: Facilitates the creation of responsive interfaces with a two-dimensional system to align and distribute elements

<Alloy>
  <Window>
    <View class="grid">
      <View class="h-40 grid-cols-2 bg-red-200">
        <Label>Column 1</Label>
      </View>

      <View class="h-40 grid-cols-2 bg-blue-200">
        <Label>Column 2</Label>
      </View>
    </View>
  </Window>
</Alloy>

Beyond Static Styles

Modern interfaces require movement and dynamism. The PurgeTSS animation module allows you to add attractive visual effects by applying 2D Matrix transformations to elements or groups of elements:

<Alloy>
  <Window>
  	<Animation id="myAnimation" module="purgetss.ui" class="zoom-in-105 duration-75"/>
  	
  	<Button id="myButton" class="w-48 rounded bg-green-500 font-bold text-white" onClick="animateMe">Touch me!</Button>
  </Window>
</Alloy>

// In your controller
function animateMe() {
  $.myAnimation.open($.myButton)
}

With this implementation, you can apply basic animations to any element. PurgeTSS installs a purgetss.ui.js module that provides animation functionality in your Titanium applications.

Transforming Development in Titanium

Adopting PurgeTSS represents a fundamental change in how we approach interface design in Titanium applications. The long-term benefits are substantial:

Faster development: Combining classes directly in XML accelerates interface implementation
Simplified maintenance: A coherent styling system facilitates changes and updates
Better performance: Smaller TSS files mean lighter applications
Greater consistency: A unified design language throughout the application
Reduced learning curve: Developers familiar with Tailwind CSS can transfer their knowledge

PurgeTSS has also been officially integrated into the Titanium SDK since version 11.0.0.GA, demonstrating its importance and adoption in the Titanium ecosystem.

By integrating PurgeTSS into your workflow, you're not just adopting a tool—you're adopting a modern methodology that has transformed web development and is now available for your Titanium projects.

Installation and Basic Usage

Installation

Install globally on your system:

npm install -g purgetss

Initialize in your project:

purgetss init

This will create a purgetss/ folder with a config.js file for easy customization.

Basic Usage

Automatic Purging Simply compile your Titanium application as you normally would. PurgeTSS will run automatically, scan your XML files, and generate a new app.tss file containing only the classes used in your views.

Manual Execution You can also run PurgeTSS manually:

purgetss

Example: Purged Styles

Consider the following index.xml file:

<Alloy>
  <Window>
    <View class="h-20 w-10/12 rounded-lg bg-gray-100">
      <Label class="text-center text-lg font-semibold text-gray-900">Welcome!</Label>
    </View>
  </Window>
</Alloy>

After running PurgeTSS, your simplified app.tss will look like this:

// Purge TSS v6.3.12
// Created by César Estrada
// https://purgetss.com

// Ti Elements
'View': { width: Ti.UI.SIZE, height: Ti.UI.SIZE }
'Window': { backgroundColor: '#FFFFFF' }

// Main Styles
'.bg-gray-100': { backgroundColor: '#f3f4f6' }
'.font-semibold': { font: { fontWeight: 'semibold' } }
'.h-20': { height: 80 }
'.rounded-lg': { borderRadius: 8 }
'.text-center': { textAlign: Ti.UI.TEXT_ALIGNMENT_CENTER }
'.text-gray-900': { color: '#111827', textColor: '#111827' }
'.text-lg': { font: { fontSize: 18 } }
'.w-10/12': { width: '83.333334%' }

Unused styles disappear, leaving a clean and optimized file!

Customization

Custom Classes and Themes

Edit purgetss/config.js to define custom spacing, colors, or extend/create utility classes:

module.exports = {
  purge: {
    // ... purge options
    options: {
      safelist: ['custom-class'], // Classes that should always be kept
    },
  },
  theme: {
    extend: { // Extend the default theme
      colors: {
        primary: '#002359',
        accent: '#9333ea',
      },
      spacing: {
        '128': '32rem', // New spacing value
      }
    },
    // You can also define custom classes here
    '.btn': {
      apply: 'h-10 w-40 bg-blue-500 text-blue-50 rounded' // Compose using other utilities
    }
  }
}

Adding Icon Fonts

To add, for example, Font Awesome icons:

purgetss icon-library --vendor=fontawesome

Then, use the icon classes directly in your XML:

<Label class="fas fa-envelope" />

Configuring Custom Typography (Text and Icons)

Place your font files (e.g., .ttf, .otf) in the purgetss/fonts/ folder.
For custom icon fonts, also include the corresponding CSS stylesheet in purgetss/fonts/. For multiple fonts, it's recommended to organize them in folders.
Generate the style definitions by running: purgetss build-fonts. This will create the purgetss/styles/fonts.tss file with the necessary classes.
Reference the fonts in your XML as you normally would.

Custom Styles for Titanium Elements

You can add or override styles for Titanium's base elements (e.g., Window, View, Label) by defining complex custom classes or composing utilities in the config.js file. PurgeTSS will merge these styles.
Make sure to include in the safelist of config.js any important classes that are applied dynamically via JavaScript to prevent them from being purged.

CLI Commands

> purgetss init: Initializes PurgeTSS configuration in your project.
> purgetss: Processes files and generates the optimized app.tss.
> purgetss icon-library: Adds icon fonts from known providers.
> purgetss build-fonts: Generates CSS classes for your custom typography.
> purgetss shades: Generates color palettes from a base color.
> purgetss color-module: Creates the color module for use in JavaScript.
> purgetss module: Installs additional UI helpers (like the animation module).

For a complete reference of commands and their options, consult the full list of Commands in the official documentation.

Best Practices

Use _app.tss for your persistent base styles and global customizations. PurgeTSS will automatically merge them.
Centralize and extend your theme definitions (colors, spacing) and composed utility classes in purgetss/config.js.
Add to the safelist any class that you apply dynamically from JavaScript or that should persist for a specific reason.
Re-run purgetss build-fonts each time you add or remove font files in the purgetss/fonts/ folder.

Frequently Asked Questions (FAQ)

Q: Will PurgeTSS delete my custom styles in _app.tss? A: No. PurgeTSS backs up your original app.tss to _app.tss (if it doesn't already exist) and intelligently merges your customizations with the generated classes each time it runs.

Q: Can I use it with LiveView? A: Yes! PurgeTSS is designed to work seamlessly with LiveView, enabling real-time style updates as you develop.

Q: Is it suitable for large and complex projects? A: Absolutely. Its automation features, optimization, and ability to maintain a clean style codebase are particularly beneficial for growing projects.

Resources and Links

Conclusion

PurgeTSS provides Titanium developers with a modern, efficient, and automated solution for style management. Its arsenal of Tailwind-inspired utility classes, robust configuration, animation and grid features, and deep integration into your workflow will help you spend less time managing style complexity and more time building impactful, high-performance apps.

If you're serious about scalability, maintainability, and modernizing your Titanium projects, PurgeTSS is an essential addition to your toolkit!

Also available in Spanish: Versión en Español