_tw Documentation

https://underscoretw.com/docs
Admin
_tw provides custom WordPress themes with Tailwind CSS, enabling quick development and efficient...
Tokens:14,196
Snippets:40
Trust Score:7.2
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install and Start Development

Source: https://underscoretw.com/docs/index

Installs project dependencies and starts the development server for live reloading. This command is essential for setting up the theme locally.

```bash
npm install && npm run dev
```

--------------------------------

### JavaScript Bundling with esbuild

Source: https://underscoretw.com/docs/development

Information on using esbuild for JavaScript bundling within the _tw framework. The documentation page linked provides examples, including how to install and bundle libraries like Alpine.js.

```javascript
// Example: Bundling Alpine.js with esbuild
// Refer to the dedicated documentation for detailed usage.
// import Alpine from 'alpinejs';
// window.Alpine = Alpine;
// Alpine.start();
```

--------------------------------

### Install npm Dependencies

Source: https://underscoretw.com/docs/installation

Installs all necessary project dependencies defined in the `package.json` file using npm. This is a prerequisite for running development scripts.

```bash
npm install
```

--------------------------------

### Install Browsersync

Source: https://underscoretw.com/docs/browsersync

Installs Browsersync as a development dependency using npm. This command adds the package to your project's `devDependencies` in `package.json`.

```bash
npm install browser-sync --save-dev
```

--------------------------------

### Run Development Build

Source: https://underscoretw.com/docs/installation

Generates a development build of the theme's stylesheet, typically for Tailwind CSS. This command compiles assets and prepares the theme for active development.

```bash
npm run dev
```

--------------------------------

### Install Composer Dependencies

Source: https://underscoretw.com/docs/installation

Installs project dependencies managed by Composer, which are used for linting, code formatting, and internationalization tools within the theme.

```bash
composer install
```

--------------------------------

### Watch for Changes with npm

Source: https://underscoretw.com/docs/development

Starts a continuous process that watches your theme files for changes and automatically regenerates the `style.css` file using Tailwind CSS. This command is essential for a smooth development workflow.

```bash
npm run watch
```

--------------------------------

### Configure Browsersync Proxy in package.json

Source: https://underscoretw.com/docs/browsersync

Adds a script to your `package.json` to start Browsersync in proxy mode. This allows synchronized testing across devices by proxying your local development domain and watching for file changes.

```json
"watch:browser-sync": "browser-sync start --proxy \"https://development-website.test\" --files \"theme\" --no-notify --no-inject-changes"
```

--------------------------------

### Import and Initialize Alpine.js

Source: https://underscoretw.com/docs/esbuild

Provides the JavaScript code required to import Alpine.js, make it available globally via the `window` object, and then start the Alpine.js framework. This enables declarative enhancements for your HTML.

```javascript
import Alpine from 'alpinejs'

window.Alpine = Alpine

Alpine.start()
```

--------------------------------

### Example package.json structure for _tw

Source: https://underscoretw.com/docs/updating

Illustrates the typical structure of a `package.json` file for a _tw theme, highlighting the `devDependencies` section where Tailwind and related build tools are managed. This is relevant for manual updates.

```json
{
  "name": "your-theme-name",
  "version": "1.0.0",
  "private": true,
  "devDependencies": {
    "@tailwindcss/typography": "^0.5.0",
    "autoprefixer": "^10.4.0",
    "cssnano": "^5.0.0",
    "postcss": "^8.4.0",
    "postcss-cli": "^9.0.0",
    "tailwindcss": "^3.0.0",
    "npm-run-all": "^4.1.0"
  },
  "scripts": {
    "build:css": "postcss src/css/style.css -o style.css"
  }
}
```

--------------------------------

### Install Alpine.js via npm

Source: https://underscoretw.com/docs/esbuild

Shows the command to install the Alpine.js library using npm, a package manager for Node.js. This is the first step before importing and using Alpine.js in your JavaScript bundle.

```plaintext
npm install alpinejs
```

--------------------------------

### Resolve npm install errors with Node.js version

Source: https://underscoretw.com/docs/troubleshooting

Addresses issues where `npm install` fails due to an incompatible Node.js version. It recommends checking and installing the latest LTS version of Node.js to ensure compatibility with project dependencies.

```bash
npm install
```

--------------------------------

### Tailwind Typography Plugin

Source: https://underscoretw.com/docs/development

Tailwind Typography is pre-installed with _tw. This section directs users to the dedicated documentation page for instructions on setting up and using the Typography plugin within their generated theme for styling HTML content.

```APIDOC
Tailwind Typography Plugin Setup:

Functionality:
  - The Tailwind Typography plugin is included by default with _tw.
  - It provides a set of zero-config styles for semantic HTML elements.

Usage:
  - To configure and use the plugin, refer to the dedicated documentation page on 'Using Tailwind Typography'.
  - This typically involves adding the `prose` class to elements you want to style.
    Example: `<article class="prose lg:prose-xl">...</article>`

Dependencies:
  - Tailwind CSS v3.0+ (included with _tw).
```

--------------------------------

### Tailwind CSS Configuration and Customization

Source: https://underscoretw.com/docs/development

Guides on customizing Tailwind CSS by modifying theme files. The `tailwind-theme.css` file is the primary location for defining design tokens and theme variables. Generated CSS files should not be edited directly.

```css
/* ./tailwind/tailwind-theme.css
   Add your design tokens in the form of Tailwind theme variables here. */

/* ./tailwind/tailwind.css
   Imports everything needed to generate style.css. */
@import "./tailwind-theme.css";

/* ./tailwind/tailwind-editor.css
   Imports everything needed to generate style-editor.css. */
@import "./tailwind-theme.css";

/* ./tailwind/tailwind-editor-extra.css
   Processed by Tailwind for block editor-only styles. */
@apply text-red-500; /* Example custom style */
```

--------------------------------

### theme.json Integration with Tailwind

Source: https://underscoretw.com/docs/development

Explains how _tw integrates with WordPress's `theme.json` file. Color and width values from `theme.json` are automatically exposed as CSS variables, allowing direct use in Tailwind classes (e.g., `bg-primary`, `max-w-content`).

```APIDOC
WordPress theme.json Integration with Tailwind CSS:

Functionality:
  - _tw automatically reads color and width values from the `theme/theme.json` file.
  - These values are exposed as CSS variables in `./tailwind/tailwind-theme.css`.

Usage:
  - Colors: Top-level colors in `theme.json` can be used directly with Tailwind classes like `bg-{color-name}` or `text-{color-name}`.
    Example: If `theme.json` has `"primary": "#3b82f6"`, you can use `class="bg-primary"`.
  - Widths: `contentSize` and `wideSize` values are available for setting `max-width`.
    Example: Use `class="max-w-content"` or `class="max-w-wide"`.

Notes:
  - Users not utilizing the block editor can safely ignore `theme.json` integration.
  - It's recommended to remove WordPress CSS variable references from `./tailwind/tailwind-theme.css` if not using the block editor to avoid potential conflicts.
```

--------------------------------

### Self-host Web Fonts with @font-face

Source: https://underscoretw.com/docs/custom-fonts

Demonstrates how to self-host web fonts using the CSS `@font-face` at-rule. This example includes font file paths relative to the theme's output CSS file (`style.css`), ensuring correct loading of font assets.

```css
@font-face {
	font-family: "Source Code Pro";
	src: url("fonts/sourcecodepro-regular.woff2") format("woff2"),
		url("fonts/sourcecodepro-regular.woff") format("woff");
	font-weight: 400;
	font-style: normal;
}
```

--------------------------------

### Troubleshoot Tailwind CSS not rebuilding with npm run watch

Source: https://underscoretw.com/docs/troubleshooting

Details potential reasons why Tailwind CSS might not rebuild after changes when `npm run watch` is active. It covers installation errors, issues with network drives or WSL, and problems caused by unsupported characters (like parentheses) in project paths affecting glob patterns.

```bash
npm run watch
```

```bash
# Example of changing --watch to --poll for Tailwind watch commands
# In package.json scripts:
# "watch:css": "tailwindcss -i ./src/input.css -o ./dist/output.css --watch"
# becomes
# "watch:css": "tailwindcss -i ./src/input.css -o ./dist/output.css --poll"
```

```plaintext
./theme/**/*.php
```

--------------------------------

### Build for Production

Source: https://underscoretw.com/docs/deployment

Executes the `npm run prod` command to create a production build. This process removes unused CSS declarations and minifies the `style.css` file, optimizing the theme for deployment.

```bash
npm run prod
```

--------------------------------

### Run Watch and Browsersync Together

Source: https://underscoretw.com/docs/browsersync

Creates a new script in `package.json` that runs both the standard project watch scripts and the new Browsersync command concurrently. This enables live reloads and synchronized testing alongside your usual development tasks.

```json
"watch-bs": "run-p watch:** browser-sync"
```

--------------------------------

### Automated Deployment with npm and GitHub Actions

Source: https://underscoretw.com/docs/troubleshooting

This snippet outlines a common strategy for automated deployments using npm scripts and GitHub Actions. It suggests running the production build command within the action to ensure all necessary generated files are present before deployment.

```yaml
name: Deploy Theme

on: [push]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
    - name: Install Dependencies
      run: npm install
    - name: Build for Production
      run: npm run prod
    - name: Deploy
      # Add your deployment steps here, e.g., copying theme files to a server
```

--------------------------------

### Bundle Theme for Deployment

Source: https://underscoretw.com/docs/deployment

Executes the `npm run bundle` command to create a zip archive of the theme for direct upload to WordPress. This command first runs `npm run prod` and then packages the `theme` folder into a zip file named after the theme slug.

```bash
npm run bundle
```

--------------------------------

### Define Standalone Browsersync Script

Source: https://underscoretw.com/docs/browsersync

Defines a dedicated script in `package.json` for running Browsersync independently. This separates it from the main watch process, allowing for more granular control.

```json
"browser-sync": "browser-sync start --proxy \"https://development-website.test\" --files \"theme\" --no-notify --no-inject-changes"
```

--------------------------------

### Bundle for Production Deployment

Source: https://underscoretw.com/docs/index

Bundles all theme assets (CSS, JavaScript, etc.) into optimized files for production deployment. This command prepares the theme for uploading to a live WordPress site.

```bash
npm run bundle
```

--------------------------------

### Expose JavaScript Functions Globally

Source: https://underscoretw.com/docs/esbuild

Illustrates how to expose a JavaScript function to the global scope by attaching it to the `window` object. This allows the function to be called from anywhere in your application.

```javascript
window.myFunction = function( myParameter ) {
	return myParameter++;
}
```

--------------------------------

### Linting and Fixing JavaScript/CSS with npm

Source: https://underscoretw.com/docs/linting-code-formatting

Commands to execute ESLint and Prettier for JavaScript and CSS files via npm scripts. These commands help catch bugs and enforce code formatting standards.

```plaintext
npm run lint
npm run lint-fix
```

--------------------------------

### Expose JavaScript Variables Globally

Source: https://underscoretw.com/docs/esbuild

Demonstrates how to make a JavaScript variable accessible globally by assigning it to the `window` object. This is crucial for variables intended to be used across different scripts or globally.

```javascript
window.myVariable = 'An important string';
```

--------------------------------

### Watch for Development Changes

Source: https://underscoretw.com/docs/index

Runs the development watcher to automatically recompile assets and reload the browser when changes are detected in theme files. This command is used during active development.

```bash
npm run watch
```

--------------------------------

### Linting and Fixing PHP with Composer

Source: https://underscoretw.com/docs/linting-code-formatting

Commands to execute PHP_CodeSniffer for PHP files via Composer scripts. These commands enforce code quality rules and formatting standards specific to PHP and WordPress.

```plaintext
composer run php:lint
composer run php:lint:autofix
```

--------------------------------

### Fix WordPress theme upload error: missing style.css

Source: https://underscoretw.com/docs/troubleshooting

Explains the error encountered when uploading a development theme zip file to WordPress, which is missing the `style.css` stylesheet. It advises manually copying the development theme into the `wp-content/themes` folder, while noting that the `npm run bundle` output is suitable for direct upload.

```plaintext
The package could not be installed. The theme is missing the style.css stylesheet.
```

--------------------------------

### Styling WordPress Navigation Menu with @apply

Source: https://underscoretw.com/docs/styling-html-from-outside-the-theme

Shows how to style the default WordPress navigation menu HTML by targeting existing classes and using Tailwind's `@apply` directive in CSS.

```CSS
#menu-header {
	@apply flex justify-between;
}

#menu-header .menu-item {
	@apply text-bold;
}
```

--------------------------------

### Enable Tailwind classes in WordPress block editor

Source: https://underscoretw.com/docs/troubleshooting

Provides solutions for when custom Tailwind classes added in the WordPress block editor are not working. It suggests safelisting classes in the Tailwind configuration file or using Twind's shim module to translate classes via JavaScript.

```javascript
// Safelist classes in your Tailwind configuration file
// Example: tailwind.config.js
module.exports = {
  content: [
    "./theme/**/*.php",
    "./templates/**/*.html",
    // ... other paths
  ],
  safelist: [
    'text-blue-500',
    'font-bold',
    // ... other classes
  ],
  // ... other configurations
};

// Or use Twind's shim module for dynamic translation
```

--------------------------------

### Update Tailwind Dependencies with npm

Source: https://underscoretw.com/docs/updating

This snippet demonstrates how to update Tailwind CSS dependencies within your _tw theme using npm. It covers the standard `npm update` command and an alternative method involving manual updates to package files.

```bash
npm update
```

```bash
# Alternative: Copy latest devDependencies and package-lock.json
# Then run:
npm install
```

--------------------------------

### Managing Generated Files in Git

Source: https://underscoretw.com/docs/troubleshooting

This snippet shows how to modify the `.gitignore` file to prevent generated CSS and JavaScript files from being ignored by Git. By removing these entries, the files will be tracked and committed alongside other theme assets.

```gitignore
# Ignore generated CSS and JavaScript files
# Remove these lines to track them in Git
# /theme/style.css
# /theme/script.js
# /theme/assets/css/*.css
# /theme/assets/js/*.js
```

--------------------------------

### WordPress Navigation Menu HTML Output

Source: https://underscoretw.com/docs/styling-html-from-outside-the-theme

Demonstrates the default HTML structure generated by the WordPress `wp_nav_menu()` function, which includes specific classes for styling.

```HTML
<div class="menu-header-container">
	<ul id="menu-header" class="menu">
		<li class="menu-item menu-item-type-post_type menu-item-object-page menu-item-1">
			<a href="https://underscoretw.com/docs/">Documentation</a>
		</li>
		<li class="menu-item menu-item-type-post_type menu-item-object-page menu-item-2">
			<a href="https://underscoretw.com/about/">About</a>
		</li>
		<li class="menu-item menu-item-type-post_type menu-item-object-page menu-item-3">
			<a href="https://underscoretw.com/contact/">Contact</a>
		</li>
	</ul>
</div>
```

--------------------------------

### Adding Utility Classes via wp_nav_menu() Arguments

Source: https://underscoretw.com/docs/styling-html-from-outside-the-theme

Illustrates how to pass utility classes directly into the `wp_nav_menu()` function arguments to control the menu's styling without modifying the HTML structure.

```PHP
wp_nav_menu(
	array(
		'container'      => false,
		'theme_location' => 'menu-1',
		'menu_id'        => 'primary-menu',
		'menu_class'     => 'flex justify-between [&_.menu-item]:text-bold',
	)
);
```

--------------------------------

### WordPress Block Editor Styles

Source: https://underscoretw.com/docs/wordpress-tailwind

Enables themes to provide custom CSS for the WordPress block editor, ensuring a consistent editing experience. This involves opting into editor styles and specifying the CSS file to be loaded.

```APIDOC
WordPress Theme Functions for Editor Styles:

1.  add_theme_support( 'editor-styles' )
    - Enables the theme to provide custom styles for the block editor.
    - This function is a prerequisite for using add_editor_style().
    - Usage: Called within the theme's functions.php file.

2.  add_editor_style( string|array $stylesheet )
    - Enqueues a stylesheet for the block editor.
    - Can accept a single stylesheet path or an array of paths.
    - The stylesheet path should be relative to the theme directory.
    - Example:
      add_theme_support( 'editor-styles' );
      add_editor_style( 'style-editor.css' );
    - Related: add_theme_support( 'editor-styles' ) must be called first.
    - Purpose: To ensure the block editor preview accurately reflects the theme's front-end styling, especially when using frameworks like Tailwind CSS.
```

--------------------------------

### WordPress wp_get_nav_menu_items Function

Source: https://underscoretw.com/docs/styling-html-from-outside-the-theme

Retrieves menu items for a given menu. It returns an array of menu items, allowing for custom HTML generation. This function is best suited for simpler menus or when custom logic is applied to reconstruct menu hierarchy.

```APIDOC
wp_get_nav_menu_items( $menu, $args = array() )

Retrieves menu items for a given menu.

Parameters:
  $menu (int|string|WP_Term): The menu to retrieve items for. Accepts menu ID, slug, or term object.
  $args (array): An array of arguments for retrieving menu items. Can include 'order', 'orderby', 'post_status', etc.

Returns:
  array: An array of WP_Post objects representing menu items, or an empty array if the menu is not found or has no items.

Notes:
  - The returned array does not preserve the menu's hierarchical structure.
  - Custom HTML output requires manual reconstruction of submenus.

Example:
  $menu_items = wp_get_nav_menu_items( 'primary' );
  if ( $menu_items ) {
    foreach ( $menu_items as $item ) {
      // Process each menu item
      echo '<li>' . esc_html( $item->title ) . '</li>';
    }
  }
```

--------------------------------

### Tailwind CSS @apply Directive

Source: https://underscoretw.com/docs/styling-html-from-outside-the-theme

The @apply directive in Tailwind CSS allows you to extract common utility classes into a single CSS class. This is useful for organizing custom components or applying styles from third-party libraries.

```css
.my-custom-button {
  @apply px-4 py-2 font-bold text-white bg-blue-500 rounded hover:bg-blue-700;
}
```

--------------------------------

### Apply Tailwind Typography Classes to Content

Source: https://underscoretw.com/docs/tailwind-typography

Demonstrates how to apply Tailwind Typography's `prose` classes to an HTML article element containing dynamic content from WordPress (`the_content()`). This allows for consistent typographic styling of CMS-generated content.

```html
<article class="prose xl:prose-lg">
	<?php the_content(); ?>
</article>
```

```html
<article class="prose prose-neutral prose-xl prose-a:text-primary">
	<?php the_content(); ?>
</article>
```

--------------------------------

### Customize Tailwind Font Family

Source: https://underscoretw.com/docs/custom-fonts

Overrides the default `font-sans` utility in Tailwind CSS to include custom font families like Oswald. This snippet demonstrates how to add custom font families to your Tailwind configuration, allowing for easy application via utility classes.

```css
@theme {
	--font-sans: "Oswald", "sans-serif";
}
```
Tokens:
Raw