Mastering Navigation in Web Components with Stencil Router

Web components offer a powerful way to build reusable and encapsulated UI elements for the modern web. As applications grow in complexity, effective navigation becomes crucial for user experience. Stencil Router provides a lightweight and efficient solution for managing navigation within web component projects built with StencilJS.

What is Stencil Router?

Stencil Router is a declarative routing library designed specifically for StencilJS applications. It allows you to define routes and associate them with specific components, enabling seamless navigation between different views within your web component-based application. Unlike traditional frameworks, Stencil Router leverages the power of web components to create a truly modular and portable navigation system.

Why Use Stencil Router?

Here are several compelling reasons to choose Stencil Router for your web component projects:

• Declarative Routing: Define your routes in a clear and concise manner using HTML-like syntax. This makes your routing logic easy to understand and maintain.
• Seamless Integration with Stencil: Stencil Router is designed to work seamlessly with StencilJS, taking advantage of its component model and lifecycle methods.
• Lazy Loading: Stencil Router supports lazy loading of components, improving initial page load times and overall application performance. This is especially important for larger applications with many routes.
• Nested Routing: Create complex navigation structures with nested routes, allowing you to organize your application into logical sections.
• Type Safety: Built with TypeScript, Stencil Router provides type safety, helping you catch errors early and improve code quality.
• SEO Friendly: Stencil Router supports server-side rendering (SSR), making your application more SEO friendly.
• Lightweight and Performant: Stencil Router is designed to be lightweight and performant, ensuring a smooth user experience.

Getting Started with Stencil Router

Let's walk through the steps of setting up and using Stencil Router in a StencilJS project.

1. Installation

First, install Stencil Router using npm or yarn:

            npm install @stencil-community/router

            

              
                Copy
              
            
          

Or using yarn:

            yarn add @stencil-community/router

            

              
                Copy
              
            
          

2. Import and Configure

Import the necessary modules in your stencil.config.ts file and configure the router:

            import { Config } from '@stencil/core';
import { sass } from '@stencil/sass';
import { Router } from '@stencil-community/router';

export const config: Config = {
  namespace: 'my-app',
  outputTargets: [
    {
      type: 'www',
      serviceWorker: null, // disable service workers
    },
  ],
  plugins: [
    sass(),
    Router({
      // Optional: Add custom configuration here
    })
  ],
};

            

              
                Copy
              
            
          

3. Define Your Routes

Create a root component (e.g., my-app.tsx) and define your routes using the <stencil-route-link> and <stencil-route> components. Make sure to import the router at the top of your component file:

            import { Component, h } from '@stencil/core';
import { RouterHistory, match } from '@stencil-community/router';

@Component({
  tag: 'my-app',
  styleUrl: 'my-app.css',
  shadow: true,
})
export class MyApp {
  render() {
    return (
      <div>
        <header>
          <h1>My App</h1>
          <nav>
            <stencil-route-link url="/">Home</stencil-route-link>
            <stencil-route-link url="/about">About</stencil-route-link>
            <stencil-route-link url="/contact">Contact</stencil-route-link>
          </nav>
        </header>

        <main>
          <stencil-route url="/" component="app-home" exact={true} />
          <stencil-route url="/about" component="app-about" />
          <stencil-route url="/contact" component="app-contact" />
          <stencil-route url="/profile/:name" component="app-profile" />
          <stencil-route component="app-not-found" />  <!-- Catch-all route for 404 -->
        </main>
      </div>
    );
  }
}

            

              
                Copy
              
            
          

Explanation:

• <stencil-route-link>: Creates a link to a specific route. The url attribute specifies the target URL.
• <stencil-route>: Defines a route and associates it with a specific component.
• url: The URL path to match.
• component: The name of the web component to render when the route matches.
• exact: (Optional) Specifies whether the route should match exactly. When set to true, the route will only match if the URL exactly matches the specified path. Useful for the homepage route.
• A route *without* a `url` attribute acts as a catch-all route, often used to display a 404 "Not Found" page.

4. Create Your Components

Create the components that will be rendered for each route (e.g., app-home.tsx, app-about.tsx, app-contact.tsx, and app-profile.tsx). For example:

            import { Component, h } from '@stencil/core';

@Component({
  tag: 'app-home',
  styleUrl: 'app-home.css',
  shadow: true,
})
export class AppHome {
  render() {
    return (
      <div>
        <h2>Home Page</h2>
        <p>Welcome to the home page!</p>
      </div>
    );
  }
}

            

              
                Copy
              
            
          

Repeat this process for the other components, creating basic content for each.

5. Handling Route Parameters

Stencil Router allows you to pass parameters in your routes. For example, in the my-app.tsx file, we defined a route for /profile/:name. To access the name parameter within the app-profile component, you can use the @Prop decorator along with the match property injected by the router:

            import { Component, h, Prop } from '@stencil/core';
import { MatchResults } from '@stencil-community/router';

@Component({
  tag: 'app-profile',
  styleUrl: 'app-profile.css',
  shadow: true,
})
export class AppProfile {
  @Prop() match: MatchResults;

  render() {
    const name = this.match && this.match.params && this.match.params.name;

    return (
      <div>
        <h2>Profile Page</h2>
        <p>Hello, {name}!</p>
      </div>
    );
  }
}

            

              
                Copy
              
            
          

Explanation:

• @Prop() match: MatchResults;: Declares a property named match of type MatchResults. Stencil Router automatically injects the match object into the component when the route matches.
• this.match.params.name: Accesses the name parameter from the match object.

Advanced Routing Techniques

Stencil Router offers several advanced features to handle more complex routing scenarios.

1. Nested Routing

You can create nested routes by defining routes within other components. This allows you to organize your application into logical sections and create more complex navigation structures. For example, within `app-about.tsx`, you could have:

            import { Component, h } from '@stencil/core';
import { RouterHistory } from '@stencil-community/router';

@Component({
  tag: 'app-about',
  styleUrl: 'app-about.css',
  shadow: true,
})
export class AppAbout {
  render() {
    return (
      <div>
        <h2>About Us</h2>
        <p>Learn more about our company.</p>

        <nav>
          <stencil-route-link url="/about/team">Our Team</stencil-route-link>
          <stencil-route-link url="/about/history">Our History</stencil-route-link>
        </nav>

        <stencil-route url="/about/team" component="app-team" />
        <stencil-route url="/about/history" component="app-history" />
      </div>
    );
  }
}

            

              
                Copy
              
            
          

You would then need to create components `app-team` and `app-history`.

2. Programmatic Navigation

Sometimes, you need to navigate programmatically (e.g., after a form submission). You can inject the RouterHistory into your component and use the push() method to navigate to a specific URL.

            import { Component, h, State } from '@stencil/core';
import { RouterHistory } from '@stencil-community/router';

@Component({
  tag: 'app-contact',
  styleUrl: 'app-contact.css',
  shadow: true,
})
export class AppContact {
  @State() message: string = '';

  submitForm = () => {
    // Simulate form submission
    setTimeout(() => {
      this.message = 'Form submitted successfully!';
      // Redirect to the home page after submission
      this.navigateTo('/');
    }, 1000);
  };

  @Prop()
  history: RouterHistory

  private navigateTo = (url: string) => {
    this.history.push(url);
  }

  render() {
    return (
      <div>
        <h2>Contact Us</h2>
        <p>Send us a message!</p>
        <form onSubmit={this.submitForm}>
          <button type="submit">Submit</button>
        </form>
        {this.message && <p>{this.message}</p>}
      </div>
    );
  }
}

            

              
                Copy
              
            
          

Important: In your `stencil.config.ts`, ensure the `Router` plugin is configured correctly. The router history object gets injected. When using programmatic navigation, you will also need to update the `app.tsx` or root component to inject the history prop, for example:

            <stencil-route url="/contact" component="app-contact" history={this.history} />
            

              
                Copy
              
            
          

3. Lazy Loading

To improve initial load times, especially in larger applications, Stencil Router supports lazy loading of components. This means that components are only loaded when their corresponding route is activated.

To enable lazy loading, make sure that your components are built as separate modules. Stencil handles this automatically when you build your project. Then, simply define your routes as usual. Stencil Router will automatically lazy load the components when needed.

For example, if your application has a large admin panel, you can lazy load the admin components so that they are only loaded when a user navigates to the admin section.

Best Practices for Using Stencil Router

Here are some best practices to follow when using Stencil Router:

• Keep Your Routes Organized: Define your routes in a logical and consistent manner. Use nested routes to organize your application into sections.
• Use Descriptive Route Names: Choose route names that are clear and descriptive. This will make your routing logic easier to understand and maintain.
• Handle 404 Errors: Always define a catch-all route to handle 404 errors (page not found). This provides a better user experience.
• Use Lazy Loading: Enable lazy loading for components that are not immediately needed. This will improve initial page load times and overall application performance.
• Test Your Routes: Thoroughly test your routes to ensure that they are working correctly. Use automated testing tools to catch errors early.
• Consider Internationalization (i18n): For global applications, consider how your routing strategy interacts with i18n. You might need to adjust routes based on the user's locale. For instance, a French user might access "/fr/about" instead of "/about". Libraries like i18next can help manage this.
• Accessibility: Ensure your routing and links are accessible to users with disabilities. Use appropriate ARIA attributes and semantic HTML.

Stencil Router in the Real World: Global Application Examples

Here are a couple of hypothetical examples of how Stencil Router could be used in real-world, global applications:

1. E-commerce Platform

An e-commerce platform could use Stencil Router to manage navigation between different product categories, product details pages, shopping cart, checkout, and user accounts. Lazy loading could be used to load product images and videos only when needed, improving performance for users with slower internet connections around the world. The routes could also be adapted based on country, offering different product catalogs based on location (e.g., "/uk/products" for the United Kingdom and "/de/products" for Germany).

2. Online Learning Platform

An online learning platform could use Stencil Router to navigate between different courses, modules, lessons, quizzes, and assignments. Nested routes could be used to organize the course content into logical sections. Programmatic navigation could be used to redirect users after completing a quiz or assignment. The platform could offer content in multiple languages, using routes like "/en/courses" (English) and "/es/cursos" (Spanish). User accounts could also be managed with routes like "/profile/:userId", allowing users to view and update their profile information. Furthermore, the platform can be compliant with different countries' data privacy laws using conditional routing.

Conclusion

Stencil Router is a powerful and flexible routing library that can greatly simplify navigation in web component applications built with StencilJS. By following the steps and best practices outlined in this guide, you can create robust and maintainable navigation systems that enhance the user experience of your web applications. With its focus on performance, modularity, and type safety, Stencil Router is an excellent choice for modern web development.