Page Rules (Deprecated)

⚠️ Deprecation Notice

Page Rules are deprecated and will be removed in a future version. Please use Conditional Rules for all new rules.

Why switch?

  • No performance difference: Conditional Rules are just as fast as Page Rules

  • Better overview: All setting changes in one place instead of spread across two pages

  • Easier debugging: Page Rules used nginx-style location logic where only the "best" match won – this made it difficult to understand which rule was actually applied. Conditional Rules are evaluated transparently in position order, so you always know exactly what happened.

  • More flexibility: Conditional Rules additionally offer rich conditions (IP, country, headers, etc.)

Migration: To migrate a Page Rule, create a Conditional Rule with a URI condition. See the migration guide below.

What are Page Rules?

Page Rules allow you to override any smoxy configuration setting based on URL patterns. They're perfect for applying different caching strategies, image optimization levels, load balancing, or any other setting to specific sections of your site.

Key characteristics:

  • Execute third in the rule sequence (after Access Rules and Rewrite Rules)

  • URL-based matching only - simple and focused

  • Evaluated in position order (1, 2, 3...)

  • First match wins, then stops - once a rule matches, no further Page Rules are evaluated

  • Can override any smoxy setting from your site configuration

Migration to Conditional Rules

Migrating from Page Rules to Conditional Rules is straightforward. Use the URI condition in Conditional Rules to achieve the same behavior.

Migration Example

Before (Page Rule):

After (Conditional Rule):

Important Differences to Note

Aspect
Page Rules
Conditional Rules

Execution

First match wins, stops

All matching rules apply

Stop behavior

Always (automatic)

Optional (stop=true)

Tip: If you want to preserve the "first match wins" behavior of Page Rules, add stop=true to your Conditional Rule.

Migration Checklist

  1. ✅ Create a new Conditional Rule with URI condition

  2. ✅ Copy over the same settings

  3. ✅ Add stop=true if you want to preserve Page Rule behavior

  4. ✅ Test the new rule with debug headers

  5. ✅ Delete the old Page Rule

Legacy Documentation

The following documentation is provided for existing Page Rules. For new rules, please use Conditional Rules.

How Page Rules Work

Page Rules are evaluated in ascending position order (1 → 2 → 3...) for every incoming request. When a rule's URL pattern matches, its settings are applied and evaluation stops.

Position-Based Evaluation

Important: Once a Page Rule matches, no further Page Rules are evaluated. This is why order matters - more specific patterns should come before general ones.

URL Matching

Page Rules match based on URL patterns using three different matchers:

Matchers

Equals (=): Exact match

Matches Regex (~): Case-sensitive regex

Matches Regex Case-Insensitive (~*): Case-insensitive regex

URL vs URI

  • URL: The complete web address including protocol and domain

    • Example: https://www.example.com/category/data.html

  • URI: Just the path without domain or protocol

    • Example: /category/data.html

Page Rules work with URIs (the path only).

Common Regex Patterns

Tip: Test your regex patterns using tools like regexr.com before applying them.

When to Use Page Rules

Use Page Rules When:

  • ✅ You need different settings for different URLs

  • ✅ Your logic is simple (just URL-based matching)

  • ✅ You want only one rule to apply (first match wins)

  • ✅ You're working with URL patterns that can be expressed with regex

Use Conditional Rules Instead When:

  • ❌ You need to match based on IPs, countries, headers, cookies, etc.

  • ❌ You want multiple rules to apply to the same request

  • ❌ You need complex AND/OR logic with multiple conditions

Settings: Override Any Configuration

Page Rules can override any setting from your site's configuration. This includes:

  • Routing: Choose different origins or load balancers

  • Caching: Control cache TTL, cache keys, cache tags, bypass cache

  • Image Optimization: AVIF, WebP, JPEG, PNG quality levels

  • Security: Enable/disable WAF, basic auth, custom error pages

  • Headers: Add, modify, or remove request/response headers

  • Optimization: HTML/JS/CSS minification

  • Advanced: Maintenance mode, debug headers, proxy timeouts

Simply select the settings you want to override when creating or editing a Page Rule. The available settings are grouped by category in the smoxy dashboard.

Use Cases & Examples

Example 1: Disable Caching for Admin Area

Scenario: Your admin panel should never be cached to ensure editors always see fresh content.

Why position 1? If you have a catch-all rule at position 1 (like /*), it would match first and your admin rule would never apply.

Example 2: High-Quality Images for Product Pages

Scenario: Product images need higher quality than the rest of your site.

Example 3: Route API Traffic to Different Backend

Scenario: Your API endpoints should be served by a different server or load balancer group.

Combined with Conditional Rules: You could add a Conditional Rule to further customize API behavior based on authentication headers or client IPs.

Rule Order Best Practices

Since Page Rules stop on first match, order is critical:

1. Most Specific Before General

2. Exact Matches Before Patterns

3. Consider Rewrite Rules

Remember that Page Rules evaluate after Rewrite Rules. Match against the rewritten URL, not the original:

Uniqueness

Each site can only have one Page Rule per unique URL pattern. If you try to create a duplicate, you'll see: "The rule for this URI already exists."

This prevents conflicting rules and ensures predictable behavior.

Common Mistakes

❌ Catch-all rule at position 1

✅ Specific before general

❌ Wrong matcher type

✅ Use regex for patterns

❌ Forgetting about rewrites

✅ Match rewritten URL

❌ Case sensitivity issues

✅ Use case-insensitive when needed

Page Rules vs Conditional Rules

When to choose Page Rules:

  • Simple URL-based logic

  • First match behavior is desired

  • You only need one rule to apply

When to choose Conditional Rules:

  • Need to match on IPs, headers, cookies, countries

  • Want multiple rules to stack/combine

  • Need AND/OR logic with multiple conditions

Can you use both? Yes! Page Rules execute first (position 3), then Conditional Rules (position 4). You can combine them:

Testing Page Rules

  1. Enable Debug Headers in your site configuration

  2. Make test requests to different URLs

  3. Check response headers to see which Page Rule matched

  4. Verify settings are being applied correctly

  5. Adjust positions if rules aren't matching as expected

Last updated

Was this helpful?