DEV Community: Chuck Carpenter

Exciting New Features in Shepherd Pro's Latest Beta Release

Chuck Carpenter — Tue, 13 Aug 2024 22:00:12 +0000

Originally published at blog.shepherdpro.com

We’re super excited to announce that Shepherd Pro has leveled up from alpha to beta. Work has been ongoing since our alpha and this release is packed with powerful new features designed to enhance your user journey configurations.

If you’ve been tuned in, you know we initially launched with analytics tied into the inner workings of our core open source library. This allows Shepherd to better inform how users of your tour are progressing and illuminating how successful the onboarding, or whatever outcome you’ve designed for, has worked. You can see a basic form of this in the Pro application and we’ve offered integrations into some popular analytics providers, like PostHog & Amplitude. This enables you to track user engagement step-by-step, gaining valuable insights to optimize your user journeys.

Since our alpha launch, we’ve worked with our users and developers to learn more about what additional features are the next most important for managing onboarding flows. We ran a Quira quest (hackathon with technology specific requirements) to work with developers implementing open source into their projects to get more feedback on the learning curve to get started.

I’ve also built journeys directly for our customers and have worked on more advanced use cases where the end user’s journey experience (e.g. whether they see a journey at all or even just particular steps along that flow) are dictated by that user’s specific criteria and activities.

It’s really exciting to see all the complex situations and ideas for journeys we’ve discovered in this time!

To build on these discoveries, we’re launching two major features as part of our beta application and javascript library updates.

Advanced Targeting Options
First are advanced targeting options where you can now add options in the application to determine if a journey is shown to your user.

User Details: Personalize journeys based on specific user attributes, such as a user’s email address or specific user id (all based on any user data you send as properties when initializing Shepherd).
Journey Interaction: Target users who have not previously seen a journey, or who may not have completed that particular journey to the final step.
URL-Specific Targeting: Trigger journeys by specific URLs for contextual relevance. For example, users who end up on a specific landing page may have a different funnel than those who are accessing your site from the home page and therefore you may want to show them different journeys that lead to different conclusions or have varying steps based on where they are currently in your application.

Seamless Journey Creation
Next, we’re introducing the ability to have your entire journey configured within the Shepherd application, and no longer limiting the configuration experience to within your application only. This is starting with simply using the same JSON configuration as would be applied directly in code, but not requiring deployments of your application for those changes to be active.

Say goodbye to a code only experience! You can now create, update, and configure journeys entirely within the Shepherd application, streamlining the process for a smoother, more intuitive experience. You no longer need to make deployments for changing text, content, order of steps, and much more.

Looking Ahead
Our journey from alpha to beta showcases our commitment to continually improving and expanding Shepherd Pro. While these updates are exciting, they’re just a glimpse into our future plans as we explore new SDKs, targeting options, and more detailed journey configurations. If there’s something you’d like to see in Shepherd Pro, please let us know.

Stay tuned for more updates, and happy journey building!

If you’re interested in learning more, schedule a demo to chat with me directly! Or join our growing Discord and see how other developers are building with Shepherd.

Introducing Shepherd Pro: Adding User Journey Analytics

Chuck Carpenter — Thu, 18 Apr 2024 04:24:05 +0000

Originally published at blog.shepherdpro.com

Hey there, it’s me Chuck Carpenter. Today I want to talk about Shepherd.js, the open source library and to announce Shepherd Pro, a way to take things further to create user journeys that are informed and effective. The TL;DR is:

An alpha launch of the Pro platform and adding analytics capabilities to the library
Chuck is building the Pro product, with continued support and help from Robbie and the OS community for the library
Sign up today at https://shepherdpro.com
Everything remains open source, MIT licensed, and we are looking for feedback on the product to help us drive things forward

As many of you know, I’ve been a maintainer of the Shepherd library for about 7 years or so. What originally started as an Ember.js add-on of an existing tour library, has been rewritten a number of times and morphed into one of the most popular user journey libraries (thanks to our 90+ contributors) with almost 12k stars! We now believe our users are looking for more while supporting the ethos of open source (we are committed to keeping the library OSS).

We’ve worked to make software that is stable, accessible, and very composable in order to allow developers to create some clever ways to help their users find functionality and value for their time (companies and projects such as Drupal, Google, and recently our friends at Codepen.io). Much of that work has also allowed us to learn a lot about maintaining/publishing dependencies and work through a few interesting patterns such as attaching an element to another, highlighting it, and programmatically reacting to user events.

Today, we’re excited to announce the alpha release of Shepherd Pro, a robust new addition to our trusted Shepherd library. Shepherd has gained and maintained popularity for its openness and expandability, and now we’re dialing it up by integrating powerful analytics capabilities. While there exists paid software where you can create onboarding tours for your application, they seem to be very focused on WYSIWYG creation and customization. Our users are very technical and are able to control all these things quite comfortably in code. Why not empower them to and give them a professional product that allows them to bring in feedback and data? These new features will transform how you understand and improve user interactions throughout their journeys.

With Shepherd Pro, you’ll have deep insights into how users interact with your guided journeys. Our new analytics tools allow you to track user engagement step-by-step, pinpointing exactly where users might disengage or need extra help. This data isn’t just informative—it’s crucial for enhancing the effectiveness of each journey and identifying areas for improvement.

While other tools exist in the market to address some of these areas, we feel that a completely open source approach that allows end product users to not only provide valuable insights but also actively contribute is critical in our path to deliver the most impactful solutions. Additionally, there are features that aren't available in other products such as:

On premise/self hosted solutions
Accessibility focus
Catering to highly technical and high performing engineering teams

The ultimate goal? To make your tours not only more engaging but also easier to navigate, boosting product adoption and user satisfaction. We aim to get users to the "aha!" moment of your application more smoothly and quickly, because a well-informed user is a happy user. Integrations extend beyond just our own tools as well. Now, Shepherd Pro easily connects with top analytics platforms like Posthog, with more integrations on the horizon. This seamless connection ensures that you can manage and analyze your user journey data effortlessly within a familiar environment.

We’re thrilled to see how Shepherd Pro will empower you to craft even more engaging and effective user journeys and we’re launching all of this to alpha users under our open source project that is MIT licensed. As we progress toward the next stages of release, we plan to add targeting options, allow you to sync your cohorts from our integrations, and eventually add ways to more easily define the configurations of a journey. Join us at https://shepherdpro.com to sign up or feel free to reach out to me directly, hello@shepherdpro.com.

Secret Handshakes and Hidden Passages: Using Redwood Functions

Chuck Carpenter — Wed, 28 Feb 2024 00:13:22 +0000

Redwood.js has served as a great choice in terms of a fully featured web application stack, covering lots of my needs such as authentication and mailing capabilities right out of the box.

For your main application, using and managing the API for your admin users is very straightforward and uses known conventions. Let's say you have perhaps another use case though? One that creates data via an action or even takes in events from another site? Enter Redwood functions.

Understanding Redwood Functions

Redwood functions are the backbone of your serverless architecture, enabling you to execute server-side logic without the overhead of managing special access points in the GraphQL that have their own custom directives and you avoid enforcing GraphQL style queries where it might be unfamilar. These functions can range from processing data, handling requests, to interacting with databases. However, without proper protection, they're like open doors to your data treasury.

Implementing API Key Authentication

To secure these precious endpoints, we turn to API keys—a unique string that a client must send to access the function. Think of it as a special passcode that unlocks your application's capabilities. Implementing API key authentication in Redwood functions ensures that only requests with the correct key can invoke your business logic.

Here’s how you might implement such a check:

export const handler = async (event: APIGatewayEvent, _context: Context) => {
  const apiKey = event.headers['x-api-key'];
  if (!apiKey) {
    return {
      statusCode: 401,
      body: JSON.stringify({
        error: "Invalid API Key",
      }),
    };
  }

  // Do your business here, good people
  return {
    statusCode: 200,
    body: JSON.stringify({
      message: "Access granted: Welcome to the secret club!",
    }),
  }
}

You might notice the event arguments on the handler function look familiar if you've worked in serverless environments before. As noted in the Redwood.js documentation:

Originally, Redwood apps were intended to be deployed as serverless functions to AWS Lambda. Whenever a Redwood app is deployed to a "serverful" environment such as Fly or Render, a Fastify server is started and your Redwood app's functions in api/src/functions are automatically registered onto the server.

Meaning, they have a similar signature to Lambdas even when in a containerized application. Huzzah!

In the above example, the function first checks if the incoming request contains an 'api-key' header that matches a predefined key stored in the environment variables. If not, it responds with a 403 Forbidden status, effectively barring the door against unauthorized access.

Why API Keys?

API keys are simple yet effective in controlling access to your functions. They help you track and control how the API is being used, preventing unauthorized use and safeguarding your application from unwanted guests.

The Tale Ends Here

Incorporating API key authentication into your Redwood functions is like equipping your digital fortress with a sophisticated locking mechanism. It ensures that your functions, whether they're updating user data, processing payments, or querying databases, remain secure and accessible only to those with the correct key.

As you continue to develop and deploy, remember that the security of your functions is integral to the integrity of your application. Secure your Redwood functions with API keys (or any other way you wish), and rest easy knowing that your back-end operations are guarded against the wild west of the web.

A Tale of Frameworks: Our Quirky Quest from Next.js to Redwood.js

Chuck Carpenter — Tue, 20 Feb 2024 21:05:37 +0000

And so it begins

In the realm of web development, choosing the right framework can feel like finding a needle in a digital haystack. Our latest project, an application for managing user journeys and getting analytics for them, started with a dive into Next.js version 14 ("blessed" with React Server Components), paired with a separate API using ElysiaJS. However, as the project continued and the complexity grew, so did our needs.

Why We Started with Next.js and ElysiaJS

Next.js, with its robust features and scalability, seemed like a natural choice. We've used it quite successfully plenty in the past and felt like an old friend to help us in our own project now, rather than enterprise client projects. React can be the wild west in some ways when it comes to compiling together all the dependencies to make it a full app framework suite, Next.js makes many of those choices for you and provides nice defaults.

Coupled with ElysiaJS for our API needs (which to be fair is quite bleeding edge and built on the newly released Bun runtime), we embarked on this journey with high hopes. Next.js offered us a modern framework with great performance, while ElysiaJS promised a flexible and fast API layer. Bun is just fast, no question.

The Twist in the Tale: Shifting to RedwoodJS

However, as we navigated through development, we encountered a few hitches. The separate management of front-end and API layers started to feel like juggling apples and oranges – doable, but unnecessarily complex. Bleeding edge tech isn't always the most documented and while open source folks are quite helpful, it's time consuming to ask questions in multiple projects and/or Discord servers. Enter RedwoodJS.

RedwoodJS offered us an integrated solution, blending the front-end and API seamlessly. It was like finding a tool that could juggle for us. The allure of its full-stack capabilities, coupled with a simpler, more cohesive development experience, was too good to pass up.

Building the App with RedwoodJS

With RedwoodJS, our development process became smoother, akin to a well-oiled machine. Its opinionated structure provided a clear path forward, reducing the overhead of decision-making. The integrated GraphQL API meant that our data management became more streamlined and all the work happened in one monorepo.

Conclusion

In the end, our journey led us to RedwoodJS, a framework that aligned perfectly with our vision for the journey management application. It reminded us that in the world of web development, flexibility and adaptability are just as important as the features a framework offers. There's something to be said for relying on web technologies that have worked well for years on end. Join us as we continue to explore and share our experiences in this ever-evolving landscape.

Innovating in the Open: Building a Product with Shepherd.js

Chuck Carpenter — Tue, 20 Feb 2024 21:02:54 +0000

Originally published at shepherdjs.dev

Web development isn’t just about slinging code – it’s about creating experiences that don’t make users want to pull their hair out. Enter Shepherd.js, our guiding light in this adventure, and our choice for steering users through journeys in our apps without getting them lost and helping to drive value every time they interact. What makes this development story unique is our approach: building in public with open source.

Why Shepherd.js?

It’s like having a GPS for your app - but without the annoying “recalculating” voice. Shepherd.js is lightweight, flexible, and doesn’t hog the spotlight, ensuring our app remains the star of the show. With this library our product isn’t just functional; it becomes more accessible and user-friendly.

Building in Public

We’re embracing the “building in public” approach. It’s like cooking with the kitchen door open – everyone sees the mess, but they also see the masterpiece in the making. This transparency invites valuable feedback and keeps us honest (and a little bit on edge).

Open Source: A Collaborative Effort

Open source is at the core of our development strategy. By making our code available to the community, we’re not just sharing our work; we’re inviting collaboration. This collective wisdom not only enhances our product but also enriches the wider open-source ecosystem. Let’s be honest, we don’t always have the best or right answers for what our customers will need and we’re happy to let them help drive us in the right direction.

Shepherd Pro: The Journey Leading Superstar

We've worked to create and iterate over this library over a number of years, and now we are taking the next step to unlock the potential capabilities of advanced user journeys with Pro. Shepherd Pro is like Shepherd.js on a caffeine boost. This enhanced offering is designed to unlock a plethora of capabilities and craft more full-featured user journeys.

Customizable Tour Templates: Like fashion templates, but for software. Dress your app in the best style that feels seemless to what your visitors are used to seeing.
Analytics Integration: Understanding user engagement is crucial. Shepherd Pro integrates analytics to provide insights into the effectiveness of the journeys, helping us make data-driven decisions.
Multi-Language Support: Parlez-vous tour? ¡Claro que sí!
User Behavior Tracking: By tracking how users interact with the tours, we gain invaluable insights. This helps us continuously optimize the user experience, making it more intuitive and effective.
Integration Capabilities: Plays well with others. No sandbox squabbles here.
Feedback Mechanisms: Because we actually want to know what you think.
Advanced Branching Logic: It's like choose-your-own-adventure, but for user journeys.

Flexible Hosting Options: Your Place or Ours

With Shepherd Pro, we’re not just handing you the keys to a sleek car; we’re giving you the choice of where to park it. Whether you’re more comfortable with us hosting, or hosting the application on your own premises or in your cloud account, Shepherd Pro adapts to your environment. Whether you’re guiding users through a complex application or a simple interface, the choice of hosting is yours. Host Shepherd Pro on your premises or in your cloud account to seamlessly integrate these journeys into your environment. It’s like choosing the perfect setting for a story – whether it’s in your own home or a cloud in the sky, we ensure the user journey remains uninterrupted and secure. This flexibility ensures that your data sovereignty and security preferences are always top priority.

Conclusion

Join us on this quirky, code-filled journey. Whether you're a developer, a tech aficionado, or just someone who appreciates a great user experience, your insights and involvement are what make this a thrilling adventure.

Simplify using MirageJS with GraphQL

Chuck Carpenter — Mon, 13 Jul 2020 04:25:57 +0000

Originally published at shipshape.io

Using Mirage can be very handy to allow app developers to build features early and not be blocked by an API that doesn't exist yet or that is still in progress. This way you can have a proof of concept or can work on features that simply need to be put in place for persistence somewhere later on.

While this works across many different application stacks, it has traditionally been used expecting a REST style API and it's not completely turn-key for some technologies such as GraphQL. A number of folks, including the Mirage core team, have been working on the best workflows to make that an easier experience, but it is not yet robustly documented. While that is underway, this is how we decided to improve our workflow as the code base grows.

Recently, we needed to apply simulation for a Javascript application using GraphQL. As part of the implementation, we worked on some utilities to streamline the developer experience for updates and maintenance. The examples for dealing with this are for a very basic use case.

import { createServer } from 'miragejs';

const graphqlSchema = buildSchema(`
  type Query {
    movies: [Movie]
  }
  type Movie {
    id: ID!
    title: String!
  }
`);

export default function () {
  createServer({
    models: {
      movie: Model
    },

    seeds(server) {
      server.create('movie', { title: 'Interstellar' });
      server.create('movie', { title: 'Inception' });
      server.create('movie', { title: 'The Dark Knight' });
    },

    routes() {
      this.post('/graphql', (schema, request) => {
        const requestJson = JSON.parse(request.requestBody);
        const query = requestJson.query;
        const variables = requestJson.variables;

        const resolver = {
          movies() {
            return schema.db.movies;
          }
        };

        return graphql(graphqlSchema, query, resolver, null, variables);
      });
    }
  })
}

This is how the basic recommended configuration is when working with GraphQl. This can work early on, but become problematic to manage when you start to have a much larger schema and need to maintain way more models and relationships for your mocking. Given the following schema:

  type Query {
    movies: [Movie]
  }
  type Actor {
    id: ID!
    movies: [Movies]!
    name: String!
  }
  type Distributor {
    id: ID!
    movies: [Movie]!
    name: String!
  }
  type Movie {
    id: ID!
    actors: [Actor]!
    distributor: Distributor!
    title: String!
  }

The first thing we can do is automate adding models to our config at build time. This can be done by parsing our schema and some traversing of the parsed AST.

import { parse } from 'graphql';

const ast = parse(`
  // ...schema
`);

// get the object definitions and fields
const nodeTypes = ast.definitions
  .filter(def => {
    if (def.kind === "ObjectTypeDefinition") {
      const { value } = def.name;

      return !["Query"].includes(value);
    }

    return false;
  })
  .map(filteredDef => {
    return {
      model: filteredDef.name.value,
      fields: filteredDef.fields
    };
  });

// output an object with model mapping
const modelMaps = nodeTypes.reduce((modelAccumulator, node) => {
  modelAccumulator[node.model] = Model;

  return modelAccumulator;
}, {});

We can then add that to the configuration for Mirage as models: modelMaps and we'll get that automatically registered as we add to our schema. This does get more complicated though, when we start to add associations in our objects and need Mirage to see that as a relationship for queries that load all that data. Ideally, the graph can work for a query like so on the UI:

query ListAllMovies {
  movies {
    actors {
      name      
    }
    distributor {
      name
    }
    title
  }
}

We first want to identify all the model names (variable modelNames). Also, we'll want to reduce the fields we're checking against to only fields that are confirmed to be other object types (variable modelsReducedFields).

  const modelNames = nodeTypes.map(type => type.model);

  const modelsReducedFields = nodeTypes.map(node => {
    const nodeFields = node.fields || [];
    const fields = nodeFields.reduce((acc, field) => {
      const { type } = field;

      const isNestedType = node => !node.name && node.type;

      if (isNestedType(type)) {
        const rootField = _getRootType(field);
        const isListType = field.type.type.kind === "ListType";
        const model = rootField.name.value;
        if (modelNames.includes(model)) {
          acc.push({
            name: field.name.value,
            model,
            isListType
          });
        }
        return acc;
      }

      return acc;
    }, []);
  return { ...node, fields };
});

Now, what we're doing here with modelsReducedFields() is taking each node and reducing the fields down to other models and determining if they are a belongs-to or has-many kind of association. You might have noticed the call to _getRootType(), which is just a recursive function to go through nested objects in the AST and get the deepest node's name. I'm showing it independently in the following:

const _getRootType = field => (field.type ? _getRootType(field.type) : field);

We can now use this improved array for the modelMaps value to get models that have the associations automatically created.

Shepherd 6.0: One Dependency, Smaller Bundle, and New Look!

Chuck Carpenter — Mon, 18 Nov 2019 16:49:00 +0000

Originally published at shipshape.io

Return to Tether

As Robert wrote about in a previous post, we moved back to the original element attachment and positioning library Shepherd.js shipped with. This was with the intent of not only controlling the overal bundle size (which I'll discuss next), but also about being able to control those dependencies over time. Since Ship Shape is now maintaining the Tether code base, we have a chance to ensure that it stays lean and performant for it's users, which are also ourselves for the future of Shepherd.

Smaller Size

Getting back to the point on overall size. For implementers of Shepherd, we find it important to make sure we're able to ship a library that adds only what is needed for the Tour API and allow engineers to create rich experiences with little impact to their application's performance. We think we've done quite a bit by reducing the overall bundle size down to ~15kb (min + gzip) and removing all dependencies other than Tether.

Website Update

As we continued to iterate, on improving the library, we decided to work with the team at make&model to create branding to help Shepherd be more memorable and unique. This now combines the demo site and branding to help show the many benefits of the library and highlight companies already using it. It also helps to show the seemingly limitless level of customization that can be achieved with Shepherd tours.

We hope this latest release provides a speedy, low impact, and easy to use way to bring application tours to your users! Feedback is appreciated, as always.