@hyext/tailwindcss

Use Tailwind CSS in hy miniapp

All styles are generated from Tailwind CSS source and not hard-coded, which makes it easy to keep this module up-to-date with latest changes in Tailwind CSS itself.

Summary

• Install
• Usage
• Supported Utilities
• API
• Customization
• Good Development Experience

Install

note: your node version should more than 11.0.0, and @hyext/builder-beyond more than 2.1.7. note: you should not install it on global node.

$ cd path/to/your/project

$ npm install @hyext/tailwindcss

Usage

Import @hyext/tailwindcss module and use any of the supported utilities from Tailwind CSS in your hy miniapp views, they are two methods to use it.

note: I suggest you shouldn't use them at the same time, because they are all big object, it will affect performance.

1. To use hycss

import UI from '@hyext/hy-ui';
import '@hyext/tailwindcss/styles.hycss';

const {SafeAreaView, View, Text} = UI;

const App = () => (
	<SafeAreaView className="h-full">
		<View className="pt-12 items-center">
			<View className="px-3 py-1 rounded-full">
				<Text className="text-3xl">Hello Tailwind</Text>
			</View>
		</View>
	</SafeAreaView>
);

2. To use tailwind API

import UI from '@hyext/hy-ui';
import tailwind from '@hyext/tailwindcss';

const {SafeAreaView, View, Text} = UI;

const App = () => (
	<SafeAreaView style={tailwind('h-full')}>
		<View style={tailwind('pt-12 items-center')}>
			<View style={tailwind('bg-blue-200 px-3 py-1 rounded-full')}>
				<Text style={tailwind('text-blue-800 font-semibold')}>
					Hello Tailwind
				</Text>
			</View>
		</View>
	</SafeAreaView>
);

tailwind function returns a simple object with styles, which can be used in any view, such as <View>, <Text> and others.

tailwind('pt-12 items-center');
//=> {
//     paddingTop: 48,
//     alignItems: 'center'
//   }

How to computed the paddingTop which value is 48 ?

Tailwind define spacing 12 is 3rem, and 1 rem represent 16px（brower base font size）, so 3 x 16 = 48.

What is different between Hycss and API?

To use styles.hycss + JSX.className, we will get a good development experiences, but styles.hycss has little different to API, it not able to use css variables, because hycss was generated by tailwind-hyext cli on compile timing, it not process any styles merge logic on runtime.

// tailwind API support *-opacity-*, like: text-opacity-50, but import hycss, it is not support this.

import tailwind from '@hyext/tailwindcss';
<View style={tailwind('text-blue-500 text-opacity-50')}></View>; // good case

import '@hyext/tailwindcss/styles.hycss';
<View className="'text-blue-500 text-opacity-50'"></View>; // bad case, text-opacity-50 is not supported by hycss

Supported Utilities

Layout

• Display (only hidden and flex)
• Overflow (only overflow-hidden, overflow-scroll and overflow-visible)
• Position (only relative and absolute)
• Top / Right / Bottom / Left (all except *-auto)
• Z-Index (all except z-auto)

Flexbox

• Flex Direction
• Flex Wrap
• Align Items
• Align Content
• Align Self
• Justify Content
• Flex
• Flex Grow
• Flex Shrink

Spacing

• Padding
• Margin

Sizing

• Width (all except w-auto and w-screen)
• Min-Width
• Max-Width
• Height (all except h-auto and h-screen)
• Min-Height (all except min-h-screen)
• Max-Height (only max-h-full)

Typography

• Font Size
• Font Style
• Font Weight
• Font Variant Numeric (only oldstyle-nums, lining-nums, tabular-nums and proportional-nums) (hycss not support)
• Letter Spacing (must be used with font size utilities)
• Line Height (only fixed line-heights)
• Text Align
• Text Color (all except text-current)
• Text Opacity (hycss not support)
• Text Decoration
• Text Transform

Backgrounds

• Background Color
• Background Opacity (hycss not support)

Borders

• Border Color
• Border Opacity (hycss not support)
• Border Style (all except border-current)
• Border Width
• Border Radius

Effects

• Opacity

Interactivity

• Pointer Events

Customization

This package exposes a tailwindcss-hyext CLI for creating a custom build of @hyext/tailwindcss using your configuration. This guide assumes that you already have Tailwind CSS and @hyext/tailwindcss installed.

1. Create Tailwind configuration

See Tailwind's official documentation on configuration to learn more.

$ npx tailwindcss init

2. Generate sources for @hyext/tailwindcss

$ npx tailwind-hyext --build json

This command will generate a styles.json file, based on your Tailwind configuration. Add this file to your version control system, because it's going to be needed when initializing @hyext/tailwindcss.

$ npx tailwind-hyext --build hycss

This command will generate a styles.hycss file, based on your Tailwind configuration + Hycss specify configuration. Add this file to your version control system, because it's going to be needed when initializing @hyext/tailwindcss.

$ npx tailwind-hyext --build both

You also generate them by cmd build option value both at the same time.

3. Create a custom tailwind() function

Use create() function to generate the same tailwind() and getColor() functions, but with your custom styles applied.

import {create} from '@hyext/tailwindcss';
import styles from './styles.json';

const {tailwind, getColor} = create(styles);

tailwind('text-blue-500 text-opacity-50');
//=> {color: 'rgba(66, 153, 225, 0.5)'}

Initializing @hyext/tailwindcss like that in every file you use it is not convenient. I'd recommend creating a tailwind.js file where you do it once and import it everywhere instead:

tailwind.js

import {create} from '@hyext/tailwindcss';
import styles from './styles.json';

const {tailwind, getColor} = create(styles);
export {tailwind, getColor};

You could also create an alias for that file, so that you could import it using an absolute path from anywhere in your project:

// Before
import {tailwind} from '../../../tailwind';

// After
import {tailwind} from 'tailwind';

API

tailwind(classNames)

classNames

Type: string[]

Array of Tailwind CSS classes you want to generate styles for.

getColor(color)

Get color value from Tailwind CSS color name.

import {getColor} from '@hyext/tailwindcss';

getColor('blue-500');
//=> '#ebf8ff'

To get a color with opacity:

import {getColor} from '@hyext/tailwindcss';

getColor('blue-500 opacity-50');
//=> 'rgba(66, 153, 225, 0.5)'

You can use Tailwind's values for color and opacity.

NOTE: For color you must NOT include the bg- prefix.

create(styles)

Create tailwind() and getColor() functions, which use custom styles. API of these functions remains the same.

See Customization.

styles

Type: object

Styles generated by tailwindcss-hyext CLI.

Good Development Experience

Tailwind Config You Should Know

They are very useful for your development.

• custom spacing

• custom colors

1. Configing your tailwind

Internal hyext tailwind config

In order to fit miniapp development, we offer a default config help developer esaliy use tailwind, it ’s concrete content as follow:

// it existed in internal of package, we not need to config it.
module.exports = {
	theme: {
		spacing: {
			0: '0px',
			1: '1px',
			2: '2px',
			4: '4px'
			96: '96px', // 0 1 2 4 6 8 ... 94 96, it is multiply by 2 from 2 to 96, but 0 and 1 reflect the value of it self.
		}
	}
};

application

{
	render() {
		return (<View className="h-50 w-50 p-12"></View>)
	}
}
// The corresponding css
// {
// 	width: 50px;
// 	height: 50px;
// 	padding: 12px;
// }

Your tailwind config

// tailwind.config.js
const colors = require('tailwindcss/colors');

module.exports = {
	theme: {
		colors: {
			transparent: 'transparent',
			current: 'currentColor',
			black: colors.black,
			white: colors.white,
			gray: colors.trueGray,
			indigo: colors.indigo,
			red: colors.rose,
			yellow: colors.amber
		},
		extend: {
			spacing: {
				700: '700px' // if your design page has unexpected size that default config without it, you can custom size you want by extension. 
			}
		}
	}
};

2. Rebuilding files about the style

$ [npx] tailwind-hyext --build both

3. Using classNames you custom

import '@hyext/tailwindcss/styles.hycss';
<View className="p-1 m-2 h-3 w-4"></View>; // It's work

Vscode Plugin

To intall Tailwind CSS IntelliSense, it can enhances the Tailwind development experience.