DEV Community: Matt Netkow

DevCon 2025 Workshop: Creating a Document Processing MCP Server

Matt Netkow — Fri, 08 Aug 2025 15:09:01 +0000

I recently led an engaging hands-on workshop at ABBYY DevCon 2025. The session, "Creating a Document Processing MCP Server," was crafted for developers eager to explore advanced workflow automation, focused on constructing a Model Context Protocol (MCP) server tailored for intelligent document processing (IDP) tasks. MCP is one of the hottest technologies in the AI ecosystem, so I was thrilled to give a presentation on its fundamentals. Here’s an overview of the workshop, its objectives, and the interactive exercises participants tackled.

👉 Want to try some hands-on MCP Server exercises? Access the workshop materials.

A deep dive into MCP servers

The workshop was centered on building an MCP server designed to streamline a typical bank account onboarding process. By integrating a range of cutting-edge tools and techniques, participants learned how to manage tasks including document uploads, data extraction, validation, and final submission.

Why MCP servers matter

Model Context Protocol, or MCP, is an open standard that bridges large language models (LLMs) with various data sources and tools, enabling developers to design dynamic workflows. The server built during this workshop demonstrated how MCP serves as both an engine and an orchestrator, bringing both determinism and scalability to complex IDP scenarios. Key features of the MCP server covered in the workshop included:

Document processing automation: Eliminate manual data entry through structured workflows.
Real-time insights and validation: Verify identity and residency documents on the fly.
Extensibility: Seamlessly integrate additional tools, prompts, and external resources as needed.

Hands-on learning experience

My main focus of the workshop was ensuring an interactive experience. I broke the material into manageable sections with practical coding exercises after each one. Participants were able to immediately apply their knowledge, receive feedback, and enhance their understanding incrementally. Here’s a high-level overview of what was covered:

1. MCP fundamentals

The session started with an introduction to MCP architecture and its benefits within document processing workflows. Attendees learned how MCP implements transports, clients, and servers to handle requests and orchestrate operations effectively.

2. Setting up and testing an MCP server

Participants began hands-on by setting up a basic MCP server, verifying its functionality using the MCP Inspector debugging tool. This phase focused on understanding the foundational structure and testing server responses to ensure accuracy.

3. Document processing with ABBYY Document AI API

The workshop progressed into integrating the ABBYY Document AI API for optical character recognition (OCR). This step highlighted the importance of leveraging robust, domain-specific OCR tools to avoid issues like hallucinated data, common with general-purpose LLMs. Attendees worked on converting utility bill uploads into structured data, demonstrating real-world applications of IDP.

4. Tool and resource management

Exercises included defining and implementing server tools to process and validate user data. Participants learned about incorporating a “human-in-the-loop” approach, ensuring secure and effective operations when handling sensitive data.

5. Extending MCP with Claude integration

Expanding the server's capabilities, participants explored integration with Claude Desktop for creating prompts and guiding workflows. This step allowed for experimenting with adaptive responses, making workflows more dynamic and user focused.

Final workflow: Bank account onboarding

At the end of the workshop, we had built a complete bank account opening workflow:

From Claude Desktop, the user enters a prompt:
"Help me open a bank account with ABBYY Bank."
The LLM, connecting to the MCP server, recognizes that the user needs to upload a utility bill.
The user uploads a utility bill and the MCP server extracts its data using the Document AI API.
If the info looks correct, the user confirms that the Server can submit the application to the bank.
The LLM responds:
"Excellent! Your bank account application has been successfully submitted to ABBYY Bank. They'll be in touch with next steps."

Explore the workshop at your own pace

While the live session provided a vibrant and collaborative atmosphere, anyone interested can take the workshop independently. To facilitate this, all code and step-by-step instructions are available in a dedicated GitHub repository:

👉 Access the workshop materials

The repository, available in Python or TypeScript, includes everything needed to build and test MCP-based workflows, from environment setup to live debugging tools and reference exercises. Developers can also experiment with the next steps suggested in the workshop, such as incorporating new validation types or extending the server for additional document workflows.

Share your journey

If you’re ready to learn MCP fundamentals and how to incorporate intelligent document processing, the "Creating a Document Processing MCP Server" workshop is an excellent place to start. Explore the repository, complete the exercises, and bring your knowledge into real-world projects.

We'd love to hear your feedback and see the innovations you build with MCP! Let us know when you've completed the workshop by tagging me @dotNetkow or @ABBYY on LinkedIn or X.

Choosing OCR Technology: Key Considerations for Software Developers

Matt Netkow — Mon, 24 Mar 2025 16:30:11 +0000

When it comes to choosing OCR (Optical Character Recognition) technology, developers have a lot to consider. Since OCR solutions have been around for decades, it’s tempting to think that they are standardized and thus, any of them will do. That couldn’t be farther from the truth: not all OCRs are created equally, so choosing the right one can still be a headache. From the type of models to AI offerings to pricing and community support, many factors play a crucial role in determining the best fit for your project. This article covers key points to keep in mind, including considerations for open source models, limitations of LLMs, and pricing.

Join the waitlist: new OCR API for AI developers coming soon

Open-source models: Cost effective, but less accurate

Open-source OCR models like Tesseract and PaddleOCR are popular choices among developers due to their accessibility and cost-effectiveness. However, they come with certain limitations:
Accuracy: Open-source models often have lower accuracy compared to commercial engines. They struggle with handwriting, rotated text, and low-quality images.
Support for complex documents: These models may not handle complex documents, tables, and charts effectively.
Continuous optimization: Enhancements to OSS models are at the whim of the community. Maintainers come and go, and their priorities often differ from your project’s needs. Proprietary companies maintain an edge through continuous optimization, leveraging years of practical experience and refined technologies.

Open-source OCR models may work for POCs or processing simple documents, but if high-quality, reliable accuracy is a must, they are a no-go.

Can LLMs replace OCR? Not so fast

LLMs like GPT-4.5 and other general-purpose AI models are increasingly being used for document processing. The ability to quickly test their OCR abilities by uploading a document through a web UI or chatbot is compelling. However, they also have their challenges:

Hallucinations: LLMs often omit significant portions of text, hallucinate content, and fail to output text coordinates.
Inconsistencies: They display inconsistent formatting and table extraction, making them less reliable for robust OCR tasks. Results themselves are inconsistent too, meaning you could process the same document ten times and get ten different results.
Speed and cost: LLM-based extraction can be slow and expensive due to high compute costs.

Due to the unpredictability of inaccuracies in large language models (LLMs), the automation of business processes is hindered. This puts significant burden on the developer to capture errors and code exceptions, feeling like a game of “LLM whack-a-mole.” Downstream, any issues missed would require users to resort to manual corrections. This defeats the purpose of introducing OCR solutions in the first place.

Pricing: Cheap may cost you more

Pricing is a critical factor when choosing an OCR solution, but it's not just about the cost.

Support and reliability: A significant benefit of paying for a solution, especially when business-critical processes depend on it, is ready access to the support, advisory, and SLAs are included.
Cost-effectiveness: Look for solutions that offer a low-cost, pay-as-you-go model, ensuring scalable solutions without unexpected expenses.
Free trials and freemium tiers: Many commercial OCR solutions offer free trials or freemium tiers, allowing developers to test capabilities before committing.
Capability comparisons: Many solutions, especially those from hyperscalers like Microsoft or AWS, appear cheap up front because they price their OCR capabilities a la carte. When compared to an all-inclusive pricing model, of course it’ll seem cheaper! Review all pricing pages carefully.

When assessing OCR solutions, seek those that provide adequate trial periods, sufficient document processing capacity, and a pay-as-you-go pricing model.

Developer support and community

A great product is not enough; comprehensive support and an active community are essential.

Documentation and SDKs: Ensure the OCR solution provides detailed documentation, SDKs, and sandbox environments to streamline integration and optimize solutions.
Community engagement: The OCR solution should have an active and friendly developer community to turn to if needed. The best encourage you to exchange ideas, get expert guidance, and enhance your OCR implementations.

The OCR world is more complex than it looks on the surface. It’s a solved problem, until you need real-world accuracy, reliability, and robust capabilities. To ensure project success, look for a strong company and community-backed solution.

Introducing ABBYY’s purpose-built Document OCR API for Developers (Coming soon)

Choosing the right OCR solution involves balancing the above factors to meet your specific needs. If your project is business critical, then ABBYY’s new Document AI platform warrants a look.

ABBYY’s upcoming Document AI API is a developer-friendly, purpose-built OCR service designed for seamless integration into AI-powered business process automation workflows. It efficiently converts unstructured business documents into structured JSON with exceptional accuracy and reliability, equipping your business solutions and application for success.

Join the Waitlist

Gating Paid Features with PropelAuth’s Role Mappings

Matt Netkow — Tue, 26 Nov 2024 21:40:37 +0000

You’ve configured your SaaS pricing plans in your payment provider of choice but need a way to tie them to your product’s roles and permissions since several features are behind a paywall. What now?

Enter PropelAuth’s Role Mappings feature, which allows the creation of multiple role and permission configurations. You can use role mappings to ensure that your product's roles and permissions can be changed as users switch between paid plans.

In this post, we’ll create free, paid, and enterprise pricing plans for a simple ticket system modeled after Zendesk, a popular ticketing and help center platform. Here’s an overview of roles and permissions that we’ll implement:

We have three roles: Owner, Manager, and Agent.
When users write to the Support team, a new issue is created. All team members can view and manage issues.
Owners and managers on the free plan can view reports covering issue resolution, but users on the Paid plan who are Owners or Managers can export them only.
Only Owners can access and change Billing across any plan since credit card details are involved.
Only Enterprise plans have the “live agent activity” feature, which shows agent statuses across all channels, how many conversations they are working on, and more.

To implement this use case, we’ll create three pricing plans using PropelAuth’s Role Mappings feature, which defines the relationship between roles and permissions.

Creating all of the pricing plans in this tutorial requires access to multiple role mappings. Upgrade to a paid plan now.

Here’s a diagram demonstrating the domain:

Implementation Steps

Follow these steps to implement free, paid, and enterprise pricing plans in PropelAuth.

1. Rename Roles

By default, PropelAuth provides Owner, Admin, and Member roles. To match the ticketing system nomenclature, rename Admin to Manager and Member to Agent. In the PropelAuth dashboard, navigate to Roles & Permissions → Roles. Click the gear icon next to each and choose Edit Name.

2. Define Permissions

Permissions in a ticket system will vary. Here are the permissions we’ll create:

Manage Billing
Manage Issues, Read Issues
Read Reports, Export Reports
View Agent Activity

To create a new permission, navigate to Roles & Permissions → Permissions. Click the Add Permission button. In this example, we’ll create the “Manage Billing” permission.

We recommend using a common structure for the IDs, such as “feature::action” where “action” is one of the CRUD operations (create, read, update, delete).

On the next screen, click to disable “Enable for all roles” then select the Owner role only since other employees shouldn’t have access to company credit card data. On the last screen, click Add Permission to create it.

3. Define Role Mappings

Most of the magic in this pricing plan use case is implemented with role mappings, which define the relationship between roles and permissions. Head over to Roles & Permissions → Mappings. First, click the three dots on the right side to rename the default role mapping to “Free,” then click Rename Mapping.

Role Mapping: Free Plan

Click into the Free plan role mapping, then choose the Mapping → Custom tab. Disable access to Export Reports on all plans since that should be a paid feature. Also, ensure owners only have Manage Billing permission.

Paid Plan Mapping

Next, create a new Role Mapping named “Paid.” Since the paid plan is mostly the same as the free one, choose the “Free” plan as the mapping to duplicate. On the next screen, keep the PropelAuth permissions the same. Next, enable Export Reports for Owners and Managers since that is a paid feature.

Enterprise Plan Mapping

The final role mapping we need is the Enterprise plan, which represents features only large businesses need. Create another new Role Mapping and copy the Paid plan mapping. In this example, our application has a “live agent activity” feature, which shows agent statuses across all channels, how many conversations they are working on, and more. This is available only to Enterprise plan users, so enable View Agent Activity permission for Owners and Managers. In application code, we can restrict Managers to only view their team's agents.

With all three pricing plans implemented, there’s one last step.

4. Subscribe Organizations to Role Mapping(s)

In order for the above role mappings to take effect, we need to assign them to organizations. Organizations in PropelAuth are groups of users that use your product together, such as companies, teams, etc. Let’s assign the fictional “NetkoOrg” company to the Enterprise pricing plan. Navigate to the Enterprise Role Mapping (Roles & Permissions → Mappings → Enterprise) then select the Subscriptions tab.

Click the Add Subscriptions button, choose the Environment, then select the organization to assign to the Enterprise role mapping.

Back on the main Role Mappings page, we can now see that one organization has been assigned to the Enterprise Role Mapping.

In application code, a simple permission check will allow only Owners or Managers in an organization tied to the Enterprise role mapping to access the agent activity feature:

const user = await validateAccessTokenAndGetUserClass(authorizationHeader);

// Owner and Manager: true
// Agent: false
// Also permitted due to being an Enterprise organization
user.hasPermission(orgId, "agent_activity::view");

We’ve created a robust pricing plan structure using PropelAuth’s Role Mappings feature in just a few steps. Now, let’s look at common real-world scenarios you and/or your users may encounter and how to handle them.

Scenarios

Owner upgrades to Paid Plan

The Owner of an organization is on the Free plan but wants access to additional features. After they upgrade to the Paid plan, grant their org access by changing their role mapping to “Paid” using subscribeOrgToRoleMapping:

auth.subscribeOrgToRoleMapping({
  orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
  customRoleMappingName: "Paid"
})

Afterward, check that they have permission to Export Reports, which will return true.

// Before - Owner and Manager: false
// After - Owner and Manager: true
user.hasPermission(orgId, "reports::export");

Owner upgrades to Enterprise Plan

Similarly, the organization Owner might upgrade to the Enterprise plan to access features unique to enterprises, such as the agent activity viewer.

auth.subscribeOrgToRoleMapping({
  orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
  customRoleMappingName: "Enterprise"
})

// Before - Owner and Manager: false
// After - Owner and Manager: true
user.hasPermission(orgId, "agent_activity::view");

Summary

PropelAuth's Role Mappings feature makes it super easy to set up different pricing plans with custom permissions. In this post, we created three roles (Owner, Manager, and Agent) and gave them varied access across Free, Paid, and Enterprise tiers. The best part? Role Mappings are flexible, so you’re now equipped with the knowledge to customize them for your app!

You'll love how simple it is to set up pricing plans with PropelAuth's easy-to-use roles and permissions system. As your app grows, you can rest easy knowing that managing user access and features will be a breeze.

PropelAuth Python v4 Release

Matt Netkow — Mon, 25 Nov 2024 22:03:17 +0000

Today, we are excited to release a new version of our base Python library, as well as releases of our framework-specific libraries for FastAPI, Flask, and Django Rest Framework.

Let’s jump in to some of the larger changes!

Better Typing Support (breaking change)

If you’ve used our Python libraries before, the type hinting left a lot to be desired. In our latest release, we now have type hints for all requests as well as datatypes for all responses.

NOTE: This will break specifically if you were previously unpacking (using the ** operator) on responses. Responses were previously dicts and are now explicit datatypes.

We have implemented commonly used functions like a key lookup (response["user_id"] will still work, but response.user_id is now preferred). We typically try to avoid breaking changes (this is our second in 3 years), but this felt like a pretty narrow problem.

User class improvements

For simpler permissions checking, you can now call functions directly on the User object like:

user.has_permission_in_org(orgId, 'can_export_reports')
user.is_role(orgId, 'Admin')
user.get_active_org().has_permission('api_key::write')

These allow you to pass around the User object instead of needing to refer back to the Auth object, and it also allows for easier mocking/testing.

New APIs

This isn’t specific to our Python library, but we’ve released a lot of new APIs like:

Force logout all user sessions
Creating a SAML setup link for your customer (which will let them manage SAML themselves)
Fetching and revoking pending invites
Support for legacy_org_id which can help you migrate from your existing setup

See the full list in our reference docs here.

Example - Easy feature gating by pricing plan

At PropelAuth, we’ve been fortunate to have a front-row seat to seeing many B2B SaaS companies grow. Auth providers are most important at critical moments in a company's history (initial launch, onboarding your first customer, closing your first enterprise customer, etc.). The most important thing we can do as you grow is to get out of the way.

That’s why we’re really happy with this FastAPI route:

@app.post("/api/expensive-action")
async def do_expensive_action(user: User = Depends(auth.require_user)):
    org = user.get_active_org()

    if org == None or \
       not org.user_has_permission("can_do_expensive_action"):
        raise HTTPException(status_code=403, detail="Forbidden")

    return do_expensive_action_inner(user, org)

At first glance, this seems like a pretty simple route, but it has a few important pieces:

The dependency injected User works with any type of authenticated user - whether it’s password, SSO, SAML, etc.
With role mappings, we can make it so an Admin of an org on our Free plan can not do the expensive feature, but an Admin of an org on our Paid plans can do the expensive action.
We can enforce that programmatically by handling a webhook from our payment provider and setting their role mapping, like so:

@app.post("/stripe/webhook")
def stripe_webhook(request):
    event = parse_and_validate_stripe_webhook(request)
    org_id = event["org_id"]

    if event["type"] == Events.CUSTOMER_SUBSCRIBED:
        # This can give the users in this organization access to increased
        # permissions, additional roles, and access to more features
        auth.subscribe_org_to_role_mapping(org_id, "Paid Plan")

    elif event["type"] == Events.CUSTOMER_UNSUBSCRIBED:
        auth.subscribe_org_to_role_mapping(org_id, "Free Plan")

    # ...

We can even give them self-serve access to advanced features like SAML and SCIM by programmatically generating a SAML connection URL, which will guide your user through setting up those features - with specific instructions for each identity provider (Okta, Azure AD, ADFS, etc.).

And the best part? That same code snippet above will continue to work. Even as our customer’s requirements get more complicated, your code won’t.

Questions? Feedback?

We're always looking to improve our libraries and services based on your feedback. If you have any questions about this release or suggestions for future improvements, please don't hesitate to reach out.

Securing a GenAI Service with API Key Validation and Trial Management

Matt Netkow — Mon, 18 Nov 2024 22:02:17 +0000

This tutorial will guide you through securing a GenAI service with a free trial and API key validation using Node.js, Express, and PropelAuth, a B2B authentication provider. We'll set up a system where users can sign up for a free 7-day trial, upgrade to a paid plan, and use their API key to generate images. The user's API key is validated on each request to generate a new image, and the trial expiration date is checked before the request is permitted.

Let's dive in and explore the key components of the user signup process, plan upgrades, and image generation workflow.

What We’ll Build

We’re building an image generation API similar to Midjourney. To complete this tutorial, we’ll leverage PropelAuth’s API Key Authentication, custom user properties, and account management features. We’ll also create an Express API with endpoints to simulate Stripe payment processing and image creation. The endpoints are:

Stripe Webhook (/webhook/stripe): Listen for when users upgrade to a paid plan or downgrade to the free plan.
Image Create (/api/image/create): Before generating an image, validate the API key and check that the user has not exceeded the seven-day trial window.

You can find the complete code on GitHub. Let’s get started!

Setting Up the GenAI Company

Begin by signing up for a free PropelAuth account if you don’t have one already. After signing up, create a project. A project includes everything you need to set up authentication, like UIs, a dashboard for managing your users, transactional emails, and more. In the dashboard, open the Signup page by navigating to the Preview button in the top right corner and choosing Signup.

The Signup page is one of several hosted pages that PropelAuth provides. Hosted pages are pre-built, customizable web pages such as signup, login, and account that integrate seamlessly with your application. It will look similar to:

We need a test user account for this application, so go ahead and sign up! Use any email you can access, including the one you signed up for PropelAuth with.

Securing the Image Creation Service

To secure access to our image creation service, we’ll require users to send an API key to an image creation API we’ll define shortly. PropelAuth provides API key management that is out-of-the-box for personal users and organization use cases. Users can create their own API keys from the Personal API Keys page. One less thing for us to build!

Head back into the PropelAuth dashboard and onto the API Key Settings page. Toggle “Personal API Keys” to ON so users can create API keys themselves.

Next, let’s add free and paid plans as an additional mechanism for verifying image creation access. This is another thing that PropelAuth can help us with! In the dashboard, navigate to User Properties. These are fields that you can use to store information about your users, such as how they use your product, their profile picture, or, in our case, the plan they are subscribed to.

Let’s create a custom User Property called plan_name. Click “Add Custom Property.” We want our users to be able to see their plan from the PropelAuth account page (more on that soon), so choose “Managed by your users,” select the type “Enum,” and enter the name “plan_name.” Once created, set the Enum Values to Free and Paid (Free | Paid).

The user should be able to view their plan at any time. To enable this, toggle “Show in Account Page.” Next, select “Not Required” since we don’t need to collect this property from users. Instead, we’ll set it behind the scenes. Finally, answer “Can Users Edit?” with “No (Read-only)” for obvious reasons— we wouldn’t want users to switch to the Paid plan without paying!

We’ve now set up the backend portion of the image creation service. Now, we can create the webhook and API that leverages the API keys and plan name custom user property.

Create the GenAI Image Creation API

To implement the image creation API, we’ll use Express.js for its simplicity and ease of use. If you have a favorite web API framework, no worries! The concepts covered below should be easy to follow.

Setting Up the Express App

Here’s a brief overview of setting up the app from scratch. You can also reference the complete code on GitHub.

$ mkdir myapp
$ cd myapp
$ npm init
$ entry point: (src/app.ts)

Though not required, the reference code repository was configured to use TypeScript, so we’ll configure it here too.

TypeScript Configuration

First, install Express, TypeScript, and Type Definitions.

npm install express typescript ts-node ts-node-dev @types/node @types/express --save-dev

Next, create a TypeScript config file:

npx tsc --init

Open tsconfig.json and configure it like so:

{
  "compilerOptions": {
    "target": "ES6",
    "module": "CommonJS",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Finally, update package.json to add a dev command for local debugging:

"scripts": {
  "dev": "ts-node-dev src/app.ts"
}

Now, we can move on to implementation. Open src/app.ts to see the basics of the Express app’s setup. The following creates the Express server running on port 3000.

import express, { Request, Response } from "express";

const app = express();
const port = 3000;

app.listen(port, () => {
  console.log(`Server is running at http://localhost:${port}`);
});

Create a “Stripe” Webhook

The first functionality we need is updating a user’s plan when they’ve upgraded to a Paid plan or downgraded to a Free one. We’d use a payment provider like Stripe to handle payment processing in a real-world app. Here’s how the workflow would work:

Incorporating Stripe or a similar payment provider is outside the scope of this tutorial, but we can simulate it easily. Create a new endpoint called

/webhook/stripe that pulls out the user ID and event name from the request body. If a new “subscription” has been created, update the user’s plan to Paid. Otherwise, if it’s been removed (downgraded), change it to “Free.”

app.post("/webhook/stripe", async (req: Request, res) => {
  const event = req.body;
  const userId = event.data.object.metadata.userId;
  switch (event.type) {
    case "customer.subscription.created":
      await updateUserPlan(userId, "Paid");
      break;
    case "customer.subscription.deleted":
      await updateUserPlan(userId, "Free");
      break;
  }

  // Return a response to acknowledge receipt of the event
  res.json({ received: true });
});

In newer versions of Express, we need to install a separate package, body-parser , to access the request body.

npm install body-parser

Import it:

import bodyParser from "body-parser";

Then, create a middleware that parses JSON:

const app = express();
const port = 3000;
const jsonParser = bodyParser.json();

Next, add the JSON parser to the webhook method signature. Now, req.body will automatically be parsed and available to us.

app.post("/webhook/stripe", jsonParser, async (req: Request, res) => { 
  const event = req.body;
}

We need to implement the functionality to change a user’s plan. As a reminder, that custom user property is defined in our PropelAuth instance. Fortunately, they provide an easy-to-use SDK.

Implementing PropelAuth

Begin by installing PropelAuth’s Express library:

npm install @propelauth/express

Next, import and call initAuth, which performs a one-time initialization of the library and verifies our image service’s API key is correct.

import { initAuth, UserMetadata } from "@propelauth/express";

const auth = initAuth({
  authUrl: process.env.PROPELAUTH_AUTH_URL!,
  apiKey: process.env.PROPELAUTH_API_KEY!,
});

Wait a minute! We don’t have an apiKey or authUrl.

Creating a Backend API Key

To update a user’s plan or validate a user’s API key, we need to connect our app to our PropelAuth instance. When we make Express library requests to PropelAuth, we’ll authenticate using a dedicated API key. To create one, head back into the PropelAuth dashboard.

Go to “Integrate your product” → “Backend Integration.”
Remain in the pre-selected “Test” environment, then click “Create New API Key.”
Enter a name and click Create.
Copy the API key immediately since you can only view it once.

You’ll also need the Auth URL, the unique URL pointing to your PropelAuth auth server. You can access that at any time.

Configure PropelAuth Express Library with Environment Files

Let’s use environment files to share the Auth URL and API Key with the PropelAuth Express library. First, install the popular dotenv package that loads environment variables from .env into Node.js projects.

npm install dotenv

Create a .env file at the project's root and copy/paste your Auth URL and the API key.

# similar values as these
PROPELAUTH_AUTH_URL=https://123.propelauthtest.com
PROPELAUTH_API_KEY=d68422536...

With those in place, process.env.PROPELAUTH_AUTH_URL will resolve correctly during the call to initAuth.

const auth = initAuth({
  authUrl: process.env.PROPELAUTH_AUTH_URL!,
  apiKey: process.env.PROPELAUTH_API_KEY!,
});

Update a User’s Plan

The PropelAuth library can authenticate our image creation service now, so the last step is adding the ability to change a user’s plan. Provide the userId and plan name to updateUserMetadata :

const updateUserPlan = async (userId: string, planName: string) => {
  await auth.updateUserMetadata(userId, {
    properties: {
      plan_name: planName,
    },
  });
};

All set! Our “Stripe” webhook is complete. If this was a real webhook, the last step is to secure the endpoint by verifying Stripe's signature. You can read more about that in the official Stripe documentation.

In the last step of this tutorial, we’ll implement the image creation endpoint, which is responsible for validating the user’s API key and allowing requests only if the user is within seven days of their free trial or on the paid plan.

Implementing the Image Creation Endpoint

This endpoint validates the user’s API key and checks if the user is still in the free trial period or has upgraded to a paid plan. Begin by creating a function to validate the user’s API key.

If the key is invalid, the auth library will throw an error. We’ll catch it and return an “Unauthorized” error.

const validateApiKey = async (apiKey: string, res: Response) => {
  try {
    return (await auth.validatePersonalApiKey(apiKey)).user;
  } catch (error) {
    res.status(401).json({ error: "Invalid API key" });
    throw new Error("Invalid API key");
  }
};

Tip: PropelAuth has a Postman collection you can download, making it easy to view and test all of PropelAuth’s backend APIs.

Next, we need to validate whether the GenAI image creation request from the user is valid. User requests are valid if they are on the free plan and it has been seven or fewer days since they signed up for an account or, of course if they are on the paid plan.

First, inspect the createdAt timestamp we get back from PropelAuth’s user object and use it to create a trial expiration date seven days from when the user’s account was created. If the user is on the Free plan and today’s date is past their trial expiration date, throw a Forbidden error.

/* Allow the GenAI request if:
- The user is on Free plan and created date isn't past 7 days OR
- The user is on Paid plan */
const validateUserIsPayingOrOnTrial = async (validatedUser: UserMetadata, res: Response) => {
  const trialExpirationDate = new Date(validatedUser.createdAt * 1000);
  trialExpirationDate.setDate(trialExpirationDate.getDate() + 7);
  const todaysDate = new Date();

  const planName = validatedUser.properties?.planName ?? "Free";
  if (planName === "Free" && todaysDate.getTime() > trialExpirationDate.getTime()) {
    res.status(403).json({ error: "Trial expired. Please upgrade to Paid plan." });
    throw new Error("Trial expired. Please upgrade to Paid plan.");
  }
};

Finally, we combine the API key validation and GenAI request methods into the Image Create endpoint. Extract the API Key from the request body and pass it to validateApiKey. If the key is valid, check that the user is permitted to make an image request. Creating a GenAI image is outside the scope of this tutorial, so instead, return a cute puppy picture.

app.post("/api/image/create", jsonParser, async (req: Request, res: Response) => {
  const apiKey = req.body.apiKey;
  const validatedUser = await validateApiKey(apiKey, res);
  await validateUserIsPayingOrOnTrial(validatedUser, res);

  // User is permitted to create an image
  // Image creation outside the scope of this example
  // Instead, return a cute puppy picture
  res.json({ imageCreated: "https://picsum.photos/id/237/200/300" });
});

Here’s the complete code:

app.post("/api/image/create", jsonParser, async (req: Request, res: Response) => {
  const apiKey = req.body.apiKey;
  const validatedUser = await validateApiKey(apiKey, res);
  await validateUserIsPayingOrOnTrial(validatedUser, res);

  // User is permitted to create an image
  // Image creation outside the scope of this example
  // Instead, return a cute puppy picture
  res.json({ imageCreated: "https://picsum.photos/id/237/200/300" });
});

/* Allow the GenAI request if:
- The user is on Free plan and created date isn't past 7 days OR
- The user is on Paid plan */
const validateUserIsPayingOrOnTrial = async (validatedUser: UserMetadata, res: Response) => {
  const trialExpirationDate = new Date(validatedUser.createdAt * 1000);
  trialExpirationDate.setDate(trialExpirationDate.getDate() + 7);
  const todaysDate = new Date();

  const planName = validatedUser.properties?.planName ?? "Free";
  if (planName === "Free" && todaysDate.getTime() > trialExpirationDate.getTime()) {
    res.status(403).json({ error: "Trial expired. Please upgrade to Paid plan." });
    throw new Error("Trial expired. Please upgrade to Paid plan.");
  }
};

const validateApiKey = async (apiKey: string, res: Response) => {
  try {
    return (await auth.validatePersonalApiKey(apiKey)).user;
  } catch (error) {
    res.status(401).json({ error: "Invalid API key" });
    throw new Error("Invalid API key");
  }
};

Test the Complete Workflow

We are code complete and can test the API we’ve created. We’ll need a personal user API key, so head back into the PropelAuth dashboard and navigate to the Account page. The easiest way is to select Preview in the upper right corner, then “Account.” This will launch your server’s Account page at a URL similar to https://123.propelauthtest.com/en/login. Log in as your test user.

Navigate to the Personal API Keys page and click “New API key.” For key expiration, choose any value you’d like. Like the server API key, copy it immediately, as it’s only shown once.

When calling the webhook, we need to send the user’s ID along with the API key. Stripe would send it automatically in production, so this is only needed for testing. In the PropelAuth dashboard, navigate to the Users page. Find the user in the Users table, click the three vertical dots on the right-hand side, and choose “Copy User ID.”

Now we’re ready to simulate what Stripe would do by testing the webhook endpoint! Start the app with npm run dev, then make a POST request to localhost:3000/webhook/stripe with the “successful payment” event in the body and the userId you copied from the dashboard. This will upgrade the user to the Paid plan.

{
    "type": "customer.subscription.created",
    "data": {
        "object": {
            "metadata": {
                "userId": "4ed07fa0-8366..."
            }
        }
    }
}

If it worked, you should see a 200 OK along with the response body:

{
    "received": true
}

Since we configured the Plan Name custom user property to be visible on the Account page, let’s verify that it was updated correctly. Back in the PropelAuth dashboard, choose the Preview button, then Account in the upper right-hand corner. Sign in to be redirected to the Settings page. Sure enough, under the Account Settings section, we can see that “Plan Name” has been set to “Paid!”

Now, let’s try the image creation endpoint. Make a POST request to localhost:3000/api/image/create and in the request body, include your API key:

{
    "apiKey": "9d14ac0d..."
}

Since our user is now a paying customer, the request should be successful, and the (hardcoded) created image should be returned:

{
    "imageCreated": "https://picsum.photos/id/237/200/300"
}

Our reward for successfully testing our API? An adorable puppy.

To recap what we’ve accomplished:

Set up PropelAuth for user and API key management
Created an Express.js app with two API endpoints for a GenAI image creation service
Created a test user and verified the API was correct

But wait, there’s more!

Bonus: Tracking API Key Signups

PropelAuth goes beyond providing auth tools. It also surfaces useful information about your customers and their users, including audit logs and exploration of company/user data. In our case, we can track how many users have signed up for an API key, which is useful for reviewing adoption over time.

Head into the PropelAuth dashboard and navigate to the Data page. Select User Audit Logs, and in the filter, choose “Created Personal API Key.” A list of all users that created a personal API key is displayed:

Summary

In this tutorial, we created an image creation service for a GenAI company. We leveraged PropelAuth’s API Key Authentication, custom user properties, and account management features for the backend and API Key management. We also created an Express.js API with endpoints to simulate payment processing and image creation. With minimal configuration and code, we’ve implemented a common API authentication use case.

Feel free to reference the complete reference code while you build your own APIs.

Protecting a Multi-tenant Next.js client/server app with PropelAuth

Matt Netkow — Wed, 06 Nov 2024 21:28:49 +0000

In this tutorial, we'll show you how to create a multi-tenant (or B2B) Next.js 14 app that creates digital coupons on demand using OpenAI's API. OpenAI will create a coupon image using a discount percentage entered by the user along with their assigned grocery store name. We'll use PropelAuth, a B2B/multi-tenant authentication provider, to ensure only authorized users can create coupons. Out-of-the-box, it provides account sign up, login, logout functionality and we’ll use their roles and permissions system to verify the user is in the correct role before allowing them to create a coupon.

You can find the complete code on GitHub. Here's what the complete app looks like:

For background, imagine a grocery store corporation. They often own multiple chains consisting of different store brands. Suppose the marketing team wants to create on-demand digital coupons for a particular chain. They want to offer an internal company-wide solution, but given a coupon's monetary savings and potential for abuse, they'll need to ensure that only authorized team members can create coupons.

The app we’ll create consists of a Next.js frontend used for generating coupons and a Next.js backend API used for communicating with OpenAI. Let's start by creating the coupon generation app.

Create the Digital Coupon App

For this app, we'll use Next.js 14. Create a new project:

npx create-next-app@14

Feel free to select the options that best suit you. I selected TypeScript, App Router, and a src directory for this tutorial's companion app, but not Tailwind. With the app created, build and start development mode:

npm run build
npm run dev

The app can now be viewed at localhost:3000. Open up src/app/page.tsx next, where we'll put the main functionality. Begin with the coupon generation markup consisting of a simple form that prompts for the grocery store name and the discount percentage to use in the generation of a new coupon image:

const [discount, setDiscount] = useState(0);
const [couponImage, setCouponImage] = useState(null);
const [isImageGenerating, setIsImageGenerating] = useState(false);

return <>
    <h2>Digital Coupon Generation</h2>
    <div>
        <form onSubmit={createNewCoupon}>
            <p>
                <label htmlFor="store">Grocery Store: </label>
                <input type="text" id="store" />
            </p>
            <p>
                <label htmlFor="discount">Discount (%): </label>
                <input 
                    type="text" value={discount} id="discount"
                    onChange={(e) => setDiscount(Number(e.target.value))}  
                />
            </p>
            <button type="submit">Generate Coupon</button>
        </form>
        {couponImage && <img src={couponImage} style={{ height: '400px' }}/>}
        {isImageGenerating && <p>Generating coupon image...</p>}
    </div>
</>

Next, add a createNewCoupon function that calls our Next.js backend API (which will call OpenAI's API soon). Pass the grocery store name and the discount to the API in the request body.

const createNewCoupon = async (event: React.FormEvent) => {
  event.preventDefault();
  try {
      setIsImageGenerating(true);
      setCouponImage(null);
      const response =
          await fetch(`/api/coupons`, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify({
                    discount: discount
                })
            })
      const data = await response.json()
      setCouponImage(data.image);
  } finally {
      setIsImageGenerating(false);
  }
}

With the frontend code in place, let's implement the backend API within our Next.js app using Route Handlers for simplicity.

Generate Coupon Images with OpenAI's API

First, install the OpenAI SDK for Node.js:

npm install openai

Under the src/app folder, create two nested folders: api/coupons. This is our Next.js API endpoint. We'll execute calls to OpenAI server-side to protect our OpenAI API key. The API operates on a "pay as you go" usage model. As of the time of writing, you must add a minimum of $5 to your account before using it, so we definitely don't want the key to fall into the wrong hands!

Create route.ts under the coupons folder. Import OpenAI so we can use their image generation capabilities, then extract the discount percentage from the request body. Set grocery store to a string placeholder for now.

// src/app/api/coupons/route.ts
import { NextResponse } from 'next/server'
import OpenAI from 'openai';

export async function POST(request: Request) {
  const body = await request.json();
  const discount = body.discount;
  const groceryStore = "orgName";
}

Next, call the OpenAI image generation service, keeping the prompt simple: a coupon for ${discount}% off any purchase at ${groceryStore}, with code ${couponCode}. Choose the DALL·E 3 model since the image quality is better, and select a size that mimics a classic horizontally printed coupon. Finally, extract the URL of the generated image and send it back in the API response.

const openai = new OpenAI();
const couponCode = generateCouponCode()

const image = await openai.images.generate({
    model: 'dall-e-3',
    size: "1792x1024",
    prompt: `a coupon for ${discount}% off any purchase at ${groceryStore}, with code ${couponCode}`
});

saveCouponCodeToDb(groceryStore, couponCode)
const imageUrl = image.data[0].url;
return NextResponse.json({ image: imageUrl })

The complete code looks like:

import { NextResponse } from 'next/server'
import OpenAI from 'openai';

export async function POST(request: Request) {
    const body = await request.json();
    const discount = body.discount;
    const groceryStore = "orgName";

    const openai = new OpenAI();
    const couponCode = generateCouponCode()
    const image = await openai.images.generate({
        model: 'dall-e-3',
        size: "1792x1024",
        prompt: 
        `a coupon for ${discount}% off any purchase at ${groceryStore}, with code ${couponCode}`
    });

    saveCouponCodeToDb(groceryStore, couponCode)
    const imageUrl = image.data[0].url;
    return NextResponse.json({ image: imageUrl })
}

Store the OpenAI Key in an Environment File

The last step in creating the coupon generation app is placing our OpenAI API key into an environment file. Create a .env file at the project's root, then add OPENAI_API_KEY= along with the API key value. Note: Be careful committing this file to source control! In a public repository, the key will be leaked.

Generate a Coupon

We have a working solution now! The app sends an API request to our backend, generates an image using OpenAI, and displays it to the end user. Here it is in action:

There's just one (major) problem: anyone at the company (or the public) can use the app!

Securing the App with PropelAuth

To secure the app quickly, we'll integrate PropelAuth, a B2B user authentication platform with easy integration and straightforward APIs for developers. Head on over to propelauth.com and create a free account. Afterward, navigate to the Frontend Quickstart in their docs. Choose "Next.js App Router" as the frontend and backend framework and follow the setup guide. It'll walk you through creating a project, setting up signup, login, and account pages, and installing and configuring PropelAuth in our Next.js app.

Go ahead, I'll wait! Come back here after completing the middleware setup step.

Note: Before continuing, ensure you have created an Organization within the PropelAuth dashboard.

In the PropelAuth dashboard, navigate to Organization Settings then under Membership Settings toggle on “User must be in at least one org” and set max number of orgs per user to “1.”

This will make sure that users must be in an organization before they are able to use your product.

Limiting Public Access with Basic Authentication

One of the great things about PropelAuth is not only how much time it saves you but also the security peace of mind it provides. To make this app feel more "complete" as well as limit public access, let's use their hosted sign-up and login pages as the first step in protecting our application.

Head back to page.tsx and import PropelAuth's library. Use the provided React hooks to retrieve user information and access login/logout functionality. We'll also retrieve the signed-in user's organization to which they belong.

// src/app/page.tsx
import {useUser, useRedirectFunctions, useLogoutFunction} from "@propelauth/nextjs/client";

export default function Home() {
    const {loading, user} = useUser()
    const {
        redirectToSignupPage, redirectToLoginPage, redirectToAccountPage
    } = useRedirectFunctions()
    const logoutFn = useLogoutFunction()
    const org = user?.getActiveOrg()

    // ... snip
}

You’ll notice the use of getActiveOrg() - this is to get the user’s active organization. Over in api/auth/[slug]/route.ts, implement the getDefaultActiveOrgId function that executes automatically for us after the user logs in. You have full control over what the active org is. Since earlier in this tutorial we configured the Organization Settings to require a user to be in one org (and only one), we can simply return that one org:

// api/auth/[slug]/route.ts
const routeHandlers = getRouteHandlers({
  postLoginRedirectPathFn: (req: NextRequest) => {
    return "/"
  },
  getDefaultActiveOrgId: (req: NextRequest, user: UserFromToken) => {
    return user.getOrgs()[0].orgId;
  },
})

Next, update the code to show a loading message when the authentication process is taking place. If the user object exists (aka an employee is signed-in), display the user's email and organization they are a part of. Finally, display Account and Logout buttons.

return (
  <div className={styles.page}>
    <main className={styles.main}>
      { loading ? <div>Loading...</div> : null }
      { user ?
        <div>
          <p>You are logged in as {user.email}</p>
          <p>You are in organization: {org!.orgName}</p>

          <button onClick={() => redirectToAccountPage()}>Account</button>
          <button onClick={logoutFn}>Logout</button>

// snip

Further down, in the else statement signifying the user hasn't signed in yet, explain that they need to sign in to use the app and provide the appropriate Login and Signup buttons.

:
<div>
  <p>You are not logged in</p>
  <button onClick={() => redirectToLoginPage()}>Login</button>
  <button onClick={() => redirectToSignupPage()}>Signup</button>
</div>

Thanks to PropelAuth, we now have a working signup and login workflow with minimal custom code required. Log into your PropelAuth account now to see the user's info displayed:

The coupon generation functionality has been placed behind a login screen but is available to all employees and the API is publicly accessible as well. Let's change that.

Limiting Employee Access with PropelAuth Roles

PropelAuth offers multiple ways to secure an app via orgs, roles, and permissions. In this example, let's use a role to define what users within each organization (grocery store) can do.

By default, PropelAuth gives us three roles: Owner, Admin, and Member. In this case, only Owners and Admins (aka grocery store managers) should be able to create new coupons. Once again, PropelAuth makes this easy. Use the isAtLeastRole function to state that users must at least be an Admin or Owner to access coupon generation:

{ user ?       
  // snip...
  <div>
    <h2>Digital Coupon Generation</h2>

    { org?.isAtLeastRole("Admin") ?
      // snip: coupon code generation
      : <p>You must be a Store Manager or Owner to create a coupon.</p> 
    }
  </div>

One last detail before we're done! Our image generation API needs to know the employee's grocery store name in order to insert it into the coupon image. Employees should only be able to generate coupons for stores where they are employed. In the store text field, automatically fill in the organization name and disable editing:

// page.tsx
<label htmlFor="store">Grocery Store: </label>
<input type="text" placeholder={org?.orgName} disabled={true} id="store" />

Here's how the app looks for a "Member" employee now:

Securing the Coupons API Endpoint

We’ve protected the frontend but still need to protect the coupons API endpoint. First, add a call to getUser() at the beginning of the request. If the user object is undefined, that means authentication has failed and we can reject the request.

export async function POST(request: Request) {
  const user = await getUser();
  if (!user) {
    return NextResponse.json({ 
        message: "You must be logged in to generate a coupon." 
      }, 
      { status: 401 }
    );
  }

// ... snip ...

Next, we want to ensure the user is a store manager or owner, just like we implemented on the frontend. Access the user’s active org, then check that their role is at least Admin:

const activeOrg = user.getActiveOrg();
if (!activeOrg || !activeOrg.isAtLeastRole("Admin")) { 
  return NextResponse.json({ 
      message: "You need to be a Store Manager or Owner to create a coupon." 
    }, 
    { status: 403 }
  );
}

As a final step, change the grocery store from a placeholder string to the active organization name:

const groceryStore = activeOrg.orgName;

Congrats! We've created a complete Next.js 14 frontend and backend API that safeguards access to coupon generation using PropelAuth's end-to-end user authentication services.

What's Next?

There are several paths to take with this grocery store app. We could add additional login methods in just a few button clicks, go deeper with authorization using permissions, and more. Happy building (and securing)!

Ionic Vue: The UI library for Vue 3

Matt Netkow — Fri, 20 Nov 2020 17:04:11 +0000

The Vue team released Vue 3 in September to much-deserved fanfare. With improved performance, smaller bundle sizes, new APIs, and a revamped foundation to support future framework iterations, it’s no wonder the Vue community is excited.

Unfortunately, many UI libraries aren’t compatible with Vue 3 yet. If you’re looking for one that is production-ready right now, then check out Ionic Vue, a UI library with over 100 mobile and desktop components built for Vue 3. Let’s take a look at everything it has to offer.

Ionic Vue: A Native Vue version of Ionic Framework

Ionic Framework is an open-source UI toolkit focused on building high-quality apps for native iOS, native Android, and the web! It’s built from the ground up with HTML, CSS, and JavaScript, so web developers should feel right at home. The components allow developers to build native experiences, all while using web technology. Now used by millions of developers, Ionic powers > 15% of all app store apps.

Ionic Vue is the native Vue version of Ionic Framework. It acts as a wrapper for the core UI component library (aptly named @ionic/core), allowing Ionic to support all Vue 3 features with ease. Here’s the entry point of an Ionic Vue app:

// Vue 3 component definition
import { IonApp, IonRouterOutlet } from '@ionic/vue';
import { defineComponent } from 'vue';

export default defineComponent({
  name: 'App',
  components: {
    IonApp,
    IonRouterOutlet
  }
});

<!-- Template with Ionic Framework UI components -->
<template>
  <ion-app>
    <ion-router-outlet />
  </ion-app>
</template>

As you can see, it’s written in modern web code. Ionic likes to say that you don’t learn Ionic, per se - you leverage your existing web development skills to build apps using their UI components.

Production Ready for Vue 3

The Ionic team released Ionic Vue shortly after the launch of Vue 3. Other libraries are still implementing Vue 3 support, so how was Ionic able to ship so fast? The answer: All Ionic Framework UI components are web components consumed by web developers using official framework bindings (including Angular, React, Vue, and basically any other JavaScript framework on the market today, or tomorrow). Developers using each framework get the experience they are familiar with, such as the framework’s routing system, lifecycle events, official APIs and tooling, and more. Frankly, it’s a win-win! Learn more about how Ionic accomplished their “Ionic for Everyone” milestone here.

That’s not all. Ever wish you could use your favorite UI library on multiple platforms but couldn’t because they didn’t leverage each platform’s specific design language? You’re in luck. Every Ionic component adapts its look to the platform the app is running on, such as Cupertino on iOS and Material Design on Android. Through these subtle design changes between platforms, developers achieve a native look and feel while users are happy to receive a high-quality app experience. This adaptation is applied automatically and is entirely configurable should you wish to make theming changes to fit your brand.

Getting Started

Creating a Vue 3-powered Ionic app is a breeze. Begin by installing the Ionic CLI:

npm install -g @ionic/cli@latest

Next, create an Ionic Vue application:

ionic start my-vue-app --type vue

After answering a few questions, you can start a local development server with ionic serve. This command uses the Vue CLI to compile your app, start a dev server, and open your app in a new browser window.

From here, you can explore Ionic’s 100+ UI components or take the “First App” tutorial that covers Ionic’s core app development concepts.

Adding Ionic Vue to an Existing Vue 3 App

If you’ve already started working on a Vue 3 app, you can add in Ionic Framework components. First, install two packages:

npm install @ionic/vue @ionic/vue-router

After that, add the IonicVue package into your app.

// main.js
import { IonicVue } from '@ionic/vue';
import App from './App.vue'
import router from './router';

const app = createApp(App)
  .use(IonicVue)
  .use(router);

router.isReady().then(() => {
  app.mount('#app');
});

Finally, there are some small routing and CSS changes to make. Once those steps are complete, you can start adding Ionic’s components to your Vue 3 app.

Bonus: Deploy your Vue 3 app to mobile

You’ve built a great Vue 3 app that works well on the web and desktop. What about native mobile? Once again, Ionic has you covered. With Capacitor, Ionic’s official cross-platform native runtime, you can deploy your Vue 3 apps as progressive web apps and iOS/Android apps, all from the same codebase.

Capacitor also provides APIs with functionality covering all three platforms. Here’s the Geolocation API, for example:

// Capacitor Geolocation plugin example
setup() {
  const locationData = ref({});

  const getLocation = async () => {
    const { Geolocation } = Plugins;
    const results = await Geolocation.getCurrentPosition();

    locationData.value = {
      lat: results.coords.latitude,
      long: results.coords.longitude
      };
    };
  return { locationData, getLocation };
}

<ion-button @click="getLocation()">Where am I?</ion-button>
<p>{{ locationData }}</p>

Notice that there’s no separate logic for each platform (“web,” “iOS,” or “Android”) in the code. That’s because Capacitor automatically detects the platform the app is running on then calls the appropriate native layer code. With Core APIs like these, coupled with full access to native SDKs and a growing roster of community-supported plugins, Capacitor empowers you to build truly native mobile apps from your Vue 3 projects.

Start Building awesome Vue 3 apps for web and mobile

If you’ve been holding off from trying Vue 3 until more libraries become compatible, now’s a great time to give Ionic Vue a try. With Ionic, you can build a fully-featured app then deploy it to multiple platforms with Capacitor.

For a more in-depth look at Ionic Vue, we recommend checking our Quickstart Guide. For a more hands-on experience, take a look at our Build Your First App Guide. If you already have a Vue 3 app, bring it to iOS and Android with Capacitor. Built something neat? Share your Ionic Vue app with us over @IonicFramework.

Converting a base64 string to a blob in JavaScript

Matt Netkow — Thu, 27 Aug 2020 14:28:13 +0000

Web browsers provide a variety of data primitives that web developers use to manage, manipulate, and store data - from plain text, to files, images, videos and more. However, using them correctly and effectively can be confusing. One such example is converting a base64 string to a blob using JavaScript. A blob represents binary data in the form of files, such as images or video. Suppose you have an image in string format that needs to be uploaded to a server. However, the available API accepts the image in blob format only. What do you do?

According to various solutions around the Internet, conversion appears to be complex. Manipulating byte arrays? No thanks. Fortunately, there's an easier, modern approach available thanks to the Fetch API. It's a powerful feature built into all web browsers that is commonly used to fetch resources across the network, like making HTTP requests to your backend APIs.

Fetch returns a Response object. As it turns out, it can convert data into more than just JSON, it can also return array buffers, form data, and blobs. In this case, we'll use blobs.

Easy as one, two

First, pass a base64 string to fetch:

const base64Data = "aGV5IHRoZXJl";
const base64 = await fetch(base64Data);

Depending on the format of the base64 string, you might need to prepend content type data. For example, a JPEG image:

const base64Response = await fetch(`data:image/jpeg;base64,${base64Data}`);

Next, convert the response to a blob:

const blob = await base64Response.blob();

That's it! From here, you can upload it to a server, display it on the screen, and more.

Bonus: Converting a blob to a base64 string

What about reversing the conversion, from a blob to a base64 string? Unfortunately, this is a bit more complicated (though if you know of a better approach, let me know in the comments!).

I encountered this real-world example recently while building a feature for the Ionifits demo app. While entering a company expense, users take a photo of the expense receipt. To implement this, I used the Capacitor Camera and Filesystem APIs.

After taking a photo, the Camera API returns a blob URL, which looks like:

https://myapp.com/cc7622aa-271b-4ee3-b707-28cbc84bc37a

To save the photo permanently to the filesystem (blobs are objects temporarily loaded into browser memory), the Filesystem API requires the data to be in base64 format, so we must convert the blob into a base64 string.

There are a variety of techniques to do so, but as a fan of asynchronous programming, I recommend creating a Promise then using the FileReader API to convert the blob:

convertBlobToBase64 = (blob) => new Promise((resolve, reject) => {
    const reader = new FileReader;
    reader.onerror = reject;
    reader.onload = () => {
        resolve(reader.result);
    };
    reader.readAsDataURL(blob);
});

const base64String = await convertBlobToBase64(blob);

Voilà! Using modern web development techniques, converting blobs and base64 strings back and forth isn’t so scary after all. What other tips or tricks have you picked up recently in your web development journey?

Special thanks to Capacitor community member Matt Wyld for his feedback, especially performance testing the Fetch approach on mobile.

Farewell, PhoneGap: Reflections on my Hybrid App Development Journey

Matt Netkow — Thu, 13 Aug 2020 12:13:56 +0000

Adobe has officially announced the shutdown of PhoneGap and PhoneGap Build.

In the context of the hybrid app development world, this is the end of an era. It's certainly the case for me: it sped up my transition from .NET to web development, and ultimately led to me landing a wonderful role at Ionic. A heartfelt thanks to the team(s) at Adobe and those in the community who supported me along the way!

PhoneGap has had such a positive impact on my career. Here's my hybrid app development journey.

From .NET to Android Development

It was 2010, and I had just bought my first smartphone - a clunky Android device. I was .NET developer building tools and WinForm desktop apps for a SaaS company. That was fun, but my work was only used by a handful of corporate clients. This Android phone had potential - I could build an "app" and reach anyone in the world via the app marketplaces? Sign me up!

I learned Java in college, so Android development was the obvious choice to learn. I bought a beginner Android book, "Hello, Android", and got to work. The dev experience was brutal to say the least. Between confusing Eclipse IDE errors and trying to understand the ins and outs of mobile development, I almost gave up multiple times.

I pushed through, and in February 2011 released the app. Frustrated that Netflix movies would expire and be removed from my instant queue without notice, I explored my options. I discovered that Netflix had an open API, and while not used on the site, every movie was assigned a "movie availability" (expiration) date!

FixMyQ was born: it displayed each movie in your Instant Queue along with its expiration date. Optionally, with one button tap, you could rearrange your entire queue by the movies expiring next. In practice, after deciding to watch something on Netflix, you could pull up my app first then pick based on what was expiring soonest:

Despite being super ugly (ha), the app worked quite well and was decently popular.

What About iOS?

The app was doing well, but I was missing out on a huge audience: iOS users. I quickly realized that targeting iOS meant that I had to completely rewrite the app - yikes! Fortunately, there was another way: PhoneGap.

Through my day job work and attending developer conferences, I noticed this thing called "JavaScript" was skyrocketing in popularity. I began to actively seek out opportunities at work to use it - landing on ASP.NET MVC, jQuery, and Knockout.js. I don't remember exactly how I found PhoneGap, but I loved the idea of "write once, run everywhere": targeting web, iOS, and Android with one code base.

Additionally, their beliefs, goals, and philosophy really struck a chord. The team recognized that the web was not a first class development platform, but they fully believed it could be, laying out a strong vision for its future.

What really stood out at the time (and still does) was this line:

"The ultimate purpose of PhoneGap is to cease to exist."

To this day, I've yet to see another project put that front and center! It made sense, though: they were committed to the "standardization of the web as a platform."

I was convinced and started building FixMyQ for iOS using PhoneGap 1.2.0. Unfortunately, I didn't get very far: Netflix deprecated then eventually shut down their open API - effectively killing the app. It was a great first mobile app project though and made for a fun retrospective.

(Not so) hilariously, in 2020 Netflix still acts like movies don't expire. C'mon, Netflix!

Hooked on Hybrid

Despite shutting down my first app, I was excited by PhoneGap's potential and got to work right away on a new app idea. Work had just bought everyone a Fitbit device. I was also in the WeightWatchers program, so I wondered what it would take to integrate them together. A few months later, Fitwatchr was born and thanks to PhoneGap, I created iOS, Android, and Windows Phone apps all from one code base:

Besides improving my web development skills, Fitwatchr was my first foray into becoming somewhat of an entrepreneur: in order to improve app sales, I learned so much about marketing, sales, and product development, ultimately earning thousands of dollars over a ~5 year timespan. As the app started making waves, I partnered with my good friend David Lapekas for design and marketing help - he was absolutely critical to my apps' success.

You might say I was "hooked on hybrid!"

My next app scratched another itch. I love craft beer and had gotten really into tracking beer tastings with Untappd (another PhoneGap/Cordova - and later, Ionic Framework - app!). Their app was great, but didn't work well in offline scenarios (such as beer festivals or inside crowded brewery tasting rooms) where cell service was weak or wifi non-existent. With BeerSwift, you can queue up the beers you're drinking, rate them, then check them all into Untappd with one button tap (once you're back online):

These apps were so much fun to build. I worked on them during the days of Angular 1, but was honestly scared off by how complex it seemed. So instead, I opted for a simpler stack: Vanilla HTML/CSS/JavaScript paired with jQuery, KendoUI Mobile for UI components, and Knockout.js for declarative bindings and automatic UI refresh.

As you can tell from those screenshots, the apps look much better than my original Android app, but the UI still has some rough edges. Someday I'll rewrite them using Ionic Framework UI components...

Enter PhoneGap Build

While PhoneGap makes it easy to create an app that runs on all platforms, in practice managing each platform is challenging, especially as a solo developer. There are nuances to each one as well as headaches with security profiles and certificates (cough cough iOS!). Enter Adobe's PhoneGap Build service, which let you build your PhoneGap-based Android, iOS, and Windows Phone apps in the cloud. It was incredibly successful as one of the early attempts at Mobile CI/CD since you could avoid wrestling with the challenges of native IDEs and tooling. Everyone in the PhoneGap community embraced it: solo devs, teams, and large companies.

After gaining lots of experience with the service, I began sharing various tips and tricks on my personal blog. I'm particularly proud of the "Cut Your PhoneGap Build App Size In Half With This One Weird Trick!" post - one of my first attempts at "marketing." 😂

Conference Talk and PhoneGap Build Pluralsight Course

It was rewarding to share what I'd learned with the community. I kept plugging away on both app development and blogging. From there, I decided to give public speaking a try, presenting a talk on hybrid app development at That Conference 2014.

By 2015, hybrid app development had become far less niche and I had built up a lot of experience with several successful apps under my belt. I looked for my next challenge and settled on creating a video course on PhoneGap Build. With only a small blog audience, I turned to Pluralsight. I was a long-time fan - they are known for their high quality courses and popular authors. After a brief audition, I was in! You can read about that 2 year journey (yeah) here. It was incredibly challenging with lots of ups and downs, but in the end, I pulled it off.

So unbelievably stoked! A long journey comes to an end. My @pluralsight course has been released! Cheers to a wonderful editorial team and @nursingaround 's support. #PhoneGap #Cordova #MobileDev

A post shared by Matt Netkow (@dotnetkow) on Jul 11, 2017 at 8:53pm PDT

The Pluralsight course was not a major hit by any means, but it was definitely a personal success: I learned basic video editing and production, and improved my writing and speaking skills along the way - all skills I would eventually use regularly in my DevRel role at Ionic.

A Hint of the Future

At some point during the development of my PhoneGap apps, I became frustrated trying to create the variety of icons and splash screens. Besides the act of creating them (I'm certainly no designer!), generating them for each platform and dimension was tedious. I'm not entirely sure, but I believe this was the first time I learned about Ionic: I stumbled upon a blog post of theirs on automating icon/splash screen generation.

I created an Ionic account just to generate those images for free with the Ionic CLI (they were originally built in the cloud). Thanks, Ionic! 😬

Little did I know where I'd end up someday...

Writing for the PhoneGap Blog

As part of the efforts to promote my PhoneGap Build Pluralsight course, I reached out to the PhoneGap team and asked about writing a post for the official blog. They graciously accepted, no doubt largely due to my course and personal PhoneGap blog posts, so I wrote "Hybrid Mobile Apps are Overtaking Native." This was a fun one: I covered the most popular concerns about hybrid app development from a fresh 2017 perspective: performance, design, frameworks, and tooling.

By then, I was a regular reader of the Ionic blog and used (borrowed?) an image of theirs for the post (Thanks again, Ionic!). It was well received and led to a bunch of native developers leaving many "spirited" comments. Ha!

Later, after the iPhone X was released, I struggled to update my PhoneGap apps to support the infamous "notch." I eventually figured out a general solution then wrote another guest post for the PhoneGap blog. To date, "Displaying a PhoneGap App Correctly on the iPhone X" is my highest viewed piece of writing ever with over 223,000 views (the notch still confuses developers to this day!).

My final post for the PhoneGap blog, "PhoneGap Devs: It’s Time to Embrace a UI Framework" was a clear call to action to the community: pick a UI framework so that you can focus on building your app instead of dealing with various mobile issues (like the iPhone notch!). By that time, I was working for Ionic so naturally the article focused on the Ionic Framework.

Huge thanks to the PhoneGap team for allowing me to guest on the blog!

Finding my Dream Job at Ionic

By the time 2018 rolled around, I was even deeper into web development, working regularly with Angular 2 and .NET Core at my day job. Angular, while initially challenging to learn, was a breathe of fresh air compared to my now-aging "PhoneGap stack."

One night, I saw a tweet from the Ionic team:

Calling all product champions! Do you have a technical background, but enjoy being the face and voice of the product, rather than sitting behind the scenes? Ionic is looking for a Senior Product Evangelist to join the team! Position can be remote! https://t.co/lHQo6OHrcJ
— ionic (@Ionicframework) April 17, 2018

The timing was simply incredible: at that moment I was taking a break from packing up my apartment. I planned to move back to Madison, Wisconsin that Summer, where Ionic headquarters is located. Leveraging my PhoneGap guest blog posts, Pluralsight course, and hybrid app experience, I landed the role as a Product Evangelist/Developer Advocate. See the full story here.

When I started building PhoneGap apps, I had no idea what it would lead to. Hybrid app development has been such an incredibly rewarding career path. After years of hard work, some luck along the way, and support from an amazing community, I'm grateful to work on hybrid app development fulltime now, and for such an awesome company as Ionic.

PhoneGap's Legacy

So as you can see, PhoneGap changed my life for the better. I owe a lot of my career to this amazing technology and the people that built it. But enough about me. 😀

Did PhoneGap succeed in its mission to make the web platform a first-class citizen?

"We believe in a web open to everyone to participate however they will. No locked doors. No walls."

Broadly speaking, PhoneGap absolutely succeeded: as pioneers of hybrid app development, they "solved" cross-platform app development challenge while also being incredibly influential in making the web a first-class development platform.

In the time since it was created - over 12 years ago - we've seen the web platform explode in popularity: the vast majority of developers are web developers and many folks new to software development learn web dev first since it's so accessible and open.

Sure, the web platform isn't perfect, but it's come a long way and will continue to evolve. It has matured a lot over the past few years, from modern JavaScript (ES6 and beyond) to package managers like npm, to built-in cross-platform browser APIs that provide rich user experiences, to the rise of Progressive Web Apps (PWAs) that fill the "gap" in "PhoneGap."

Now, all of us at Ionic are ready to carry the torch as the modern leader of cross-platform hybrid app development. Our native runtime tool Capacitor, as a spiritual successor to PhoneGap, offers a modern, web-first approach to hybrid and is backward compatible with PhoneGap.

Thank you to Adobe and the PhoneGap team for their hard work over the years and helping so many developers embrace web development. Long live the web platform!

Hosting Ionic Meetups Online

Matt Netkow — Wed, 15 Apr 2020 15:08:57 +0000

A few weeks ago, we shared how the Ionic community is tackling the COVID-19 crisis by building apps to help inform the public.

The efforts are incredibly inspiring - while COVID has upended normal life and forced us inside, that doesn’t mean that the community’s desire to connect with other members or learn new skills has stopped. Quite the opposite, in fact.

During the early days of Ionic, hosting meetups was a great way to connect with local community members, improve your web development skills, and keep up to date with the latest in Ionic tech. So, to help facilitate our community learning and growing together, we’re putting renewed effort into making Ionic Meetups easy and fun again.

Using a variety of free online tools and resources, hosting a virtual Ionic meetup has never been easier. Here are a few resources and guides that we’ve put together to help you get started, starting with a list of pre-built presentations (including one that’s brand new for Ionic React), along with Meetup Pro support for qualified groups.

New Ionic React Presentation, Powered by DeckDeckGo

Launched late last year, the reception to Ionic React has been wonderful. As part of our rebooted Ionic Meetup effort, we’ve created a brand new presentation on Ionic React. View the online version here and the code here. Take a look and let us know what you think in the comments.

Staying true to our love of web technologies, the presentation is actually a standalone progressive web app (PWA) built using Web Components and Ionic Framework components. Would you expect anything else? 🚀

To pull this off, we didn’t have to look very far - a couple of talented Ionic Community members had already built an awesome solution: DeckDeckGo, an open source presentation creator. Needless to say, we’re big fans of David and Nicolas’ work: from running the Ionic Zurich Meetup group to blogging often about web development (and Stencil!), and even guesting on the Ionic Podcast. A big thank you from the Ionic team for creating such an awesome tool! 💙

Additional Ionic Presentations

But wait, there’s more! We have additional presentations available as publicly viewable Google Slide decks:

What is Ionic? covers how to build mobile apps using web technology.
What is Capacitor? covers Ionic’s official native runtime used to package and deploy Ionic apps for various platforms including iOS, Android, Electron, and PWAs.
What is Stencil? covers Ionic’s Web Component Compiler that makes it easy to create web components that run everywhere, without the need for a framework.

The best part about these presentations is that they’re easy to share informally with friends and co-workers. However, if you’re presenting to a group and you want something more official, we recommend virtual Meetups.

Easy Online Meetups, Powered by Meetup.com

For a more “official” approach, Ionic recommends Meetup.com. While in-person events are (understandably) on hold, you can still host an online Meetup.

We encourage anyone that is interested in Ionic and web development in general to start an Ionic Meetup.

Register a new Meetup group

When registering your new Ionic group, there are just a few details to note:

Choose relevant topics: Be sure to choose Ionic Framework. Meetup automatically helps new groups find members by referring them to groups that match their chosen interests, so setting the right topics is key. Additional topics to set include: Hybrid Apps, Web Development, JavaScript, Angular, React, and Mobile Development.
Group name: Keep it simple, such as “Ionic [City Name]”.
Describe the group: Keep it light and friendly. A sample you can use:

Ionic [location] is centered around Ionic, a free, cross-platform, open source platform for building native, mobile, desktop, and progressive web apps. Come connect with web developers of all skill levels to share resources, learn, and discuss app development topics, including the latest new features of Ionic’s technology, web dev best practices, native enhancements, Progressive Web Apps, performance, and more.

Meetup also has a great guide on starting a new group.

Create your first event

Online hosting is a great, low friction way to get started. As an added bonus, Meetup now makes it easy to host an online event - simply click “Make this an online event” under Location then add the event link.

Creating a presentation is hard work - so don’t bother! Pick a topic that you’re most comfortable with then leverage the relevant Ionic presentation template above.

Start Promoting

Start by inviting your friends and coworkers to your first Meetup, then expand from there.

Additionally, send an email to meetup@ionicframework.com with the link to your new Meetup group. You can also share your link on social media - tag us on Twitter (@IonicFramework) and we’ll help spread the word about your new group!

Become an Official Ionic Meetup

The most active Ionic Meetups are eligible to earn Official status (see the official group list here.

Meetup charges Organizers a small monthly fee. However, when you become an official Ionic Meetup, we’ll not only pay Meetup’s costs, but you’ll also unlock periodic access to Ionic swag. Simply host 3 consistent Meetups then send us an email (meetup@ionicframework.com) for next steps.

For Official groups looking to relaunch their meetup, we’ve created new event templates, featuring each of the Ionic presentations mentioned above. Choose one after clicking “Schedule an Event.”

Host an Ionic Meetup Today

With the entire world hanging out online, it’s never been a better time to connect with the web development community. Consider starting an Ionic Meetup today, and let us know what you think of the presentations in the comments below. What others should we create? 🍻

Join us Tuesday, April 21st

To kick off the Ionic Online Meetup movement, I’ll be presenting on Ionic React in partnership with Ionic Zürich. Come learn about Ionic’s support for this popular web framework, then stay for a live Q&A session afterward.

Of course, it’s online - anyone can join us! RSVP here.

Announcing Capacitor 2.0

Matt Netkow — Wed, 08 Apr 2020 17:10:36 +0000

Today I’m thrilled to announce the 2.0 release of Capacitor, Ionic’s native runtime that makes it easy to build web apps that run on iOS, Android, and on the web as Progressive Web Apps— all powered by a single codebase.

Developers use Capacitor as a native app container for packaging and deploying their Ionic apps to various mobile and desktop platforms. Capacitor allows them to access native features like the Camera using the same code across all platforms - without having to worry about platform-specific details.

This new version updates Capacitor and its project templates to the latest security, bug fixes, and features including:

Swift 5 and Xcode 11+ support
Android 10 (SDK 29) and AndroidX support, which makes Face Unlock and Iris Unlock available now in Ionic Identity Vault.
Bug fixes and usability improvements to 23+ core plugins

Why Capacitor?

Traditionally, web developers have turned to tools like Apache Cordova/Adobe PhoneGap to deploy their web apps to other platforms. This worked well for many years, with Ionic recommending Cordova as the default method for targeting native iOS and Android platforms. Over time our opinions changed about how this layer should work and after exploring various ideas, determined the best option was to bring the native runtime component of app building in-house.

Now a key part of the Ionic Platform, Capacitor makes it easy for web developers to reuse their skills to build quality apps for all platforms, while significantly lessening the likelihood that they’ll get stuck on native-specific issues. You can learn more about how Capacitor compares with Cordova in this article penned by Max.

Capacitor 2.0 updates its underlying technology to support the latest versions of programming languages and operating systems that power all Capacitor apps, enabling improved performance, security, and modern development experiences. Specifically, support for the latest tech from iOS and Android is now available.

Swift 5 and Xcode 11+

On the iOS front, this means Swift 5 and Xcode 11+ support. This brings smaller app bundle sizes, modern development tooling and features, and compatibility with earlier versions of Swift.

Android 10 (SDK 29) and AndroidX

On Android, this means Android 10 (aka SDK 29), with improved security and biometrics, audio/video capabilities, and system-wide dark mode.

Additionally, AndroidX, the next generation of the Android Support Library, is now supported. Both provide Android developers with a standard way to provide users with newer features on earlier versions of Android or graceful fallback when unavailable.

AndroidX replaces the Support Library, providing feature parity and backward-compatibility while also bringing improvements to library modularity, smaller code size, and a better developer experience.

Whether you’re a consumer of Capacitor or a plugin author, you simply need to update your projects (or CLI) to access these new capabilities (see below).

Improved Plugins, Tooling, and Docs

Capacitor 1.0 wouldn’t have been as successful as it has been without a solid developer experience backing it. With Capacitor 2.0, we’ve reviewed it from head to toe, leading to updates to the core plugins, the CLI tooling, and documentation.

Fundamentally, if you’re going to build unique app experiences, you need a reliable set of plugins to build on top of. Capacitor 2.0 includes many updates to its 23 core plugins, from bug fixes to new features to usability improvements. Many of these changes were driven by feedback from you, the Ionic community, so thank you! We appreciate your efforts and feedback - it helps us ensure that it’s never been easier to get started with Capacitor.

Speaking of awesome community efforts, Ionic’s official tool for generating splash screens and icons, cordova-res, just got a big update: Capacitor support! Thanks to wannadream for this contribution.

npm i -g cordova-res
cordova-res --skip-config --copy

With this expanding scope, I guess we’ll have to rename it!

Capacitor’s embrace of native tooling means that it’s never been easier to implement more creative native features. That said, the nuances and details can be challenging, so we’ve begun to add new implementation guides to the Capacitor docs, including Deep Links, Sign In with Apple and a refreshed Push Notifications with Firebase guide. There are more coming soon - if there’s content you think is missing, please let us know in the comments.

Sign In with Apple

Sign in with Apple offers users the ability to sign into apps and websites using their Apple ID. Benefits include a focus on security (automatic two-factor authentication and user activity is not tracked) and users can start using your app right away (bypassing traditional sign-up measures).

As of April 2020, apps that use a third-party or social login service are required to offer Sign in with Apple as an option as well. This includes Facebook, Twitter, Linkedin, and Google.

The community-driven Capacitor Sign in with Apple plugin offers an easy implementation process out of the box. Simply install the plugin, configure the native iOS project, then move on. Learn how here.

Android Face Unlock & Iris Unlock

In order to protect your user’s data, you need to keep up with the latest mobile security features. Security is traditionally challenging to implement correctly - with disastrous results if done wrong.

With the new support of AndroidX in Capacitor 2.0, Ionic Identity Vault now supports Android’s Face Unlock and Iris Unlock. This update to Ionic’s all-in-one frontend identity management system brings industry-leading facial and iris authentication features to the Android platform. Using a simple API, you can add top of the line biometric authentication to your Capacitor apps. Learn more here.

Coming Soon: CORS is no more!

Speaking of listening to dev feedback - we’ve got a new plugin in the works that should alleviate most of the pain Ionic developers feel when accessing external data & APIs on mobile.

Cross-Origin Resource Sharing (CORS) is a mechanism that browsers and webviews — like the ones powering Capacitor — use to protect your user's data and prevent attacks that would compromise your app.

While great for security, this commonly restricts HTTP/S requests - the mechanism through which developers access and manage external data - leading to lots of confusion. Ultimately, this is a distraction that takes away time and focus better spent building apps.

Soon, we’ll introduce a new HTTP plugin that addresses this automatically in a cross-platform approach. On mobile, HTTP requests are executed natively, outside the webview. This effectively bypasses CORS, resulting in an improved developer experience while maintaining proper security protocols (native apps are not subjected to CORS). Web requests use fetch, the modern web browser API for retrieving external resources.

The HTTP plugin is in active development. We’d love for you to test it and provide feedback. You can also check out our CORS troubleshooting guide in the meantime.

An update on Electron support

After taking a hard look at what our priorities and focus needs to be in 2020, we've decided to put Electron support back into beta. After additional investment in key platforms that generate the most interest (iOS, Android, and PWAs), we'll revisit it.

Easy Update Process

Capacitor gives Ionic developers complete control of their native projects. Among many other benefits, this makes updating easy and straightforward.

First, update Capacitor Core and the CLI:

cd your-app-folder
npm install @capacitor/cli@latest
npm install @capacitor/core@latest

Next, update each Capacitor library in use:

npm install @capacitor/ios@latest
npx cap sync ios

npm install @capacitor/android@latest
# Within Android Studio, click “Sync Project with Gradle Files” button

cd electron
npm install @capacitor/electron@latest

Then, follow these update instructions which cover one-time manual steps:

More than a version number

Capacitor 2.0 is a significant update to an increasingly important part of Ionic’s app development platform.

We’ve been blown away by the reception of Capacitor since it was announced, and installs have been growing quickly.

With 2.0, we are starting to make Capacitor the default for all new Ionic React and soon Ionic Angular projects, and expect us to be recommending Capacitor for all new Ionic apps and increasingly for enterprise apps as well.

Additionally, we are dedicating more internal resources to Capacitor as it becomes a key part of the Ionic offering. Expect to see Capacitor receive a lot more focus and attention from us in the coming months.

Start building today

If you’re new to Capacitor, it’s easy to get started. Follow our complete First App guide to build a Photo Gallery app powered by the Capacitor Camera, Filesystem, and Storage APIs. For those looking to dive in right away, check out the Ionic App Wizard - generate a great Capacitor starter app in seconds.

Thanks to Capacitor, I’ve fallen in love with mobile development again

Matt Netkow — Fri, 13 Mar 2020 13:37:00 +0000

Long before joining Ionic, I built web-based apps (using jQuery and Knockout.js!) and deployed them to iOS and Android using Cordova. They weren’t pretty (I didn’t have something like this 😉 available), the code was messy, but they got the job done: I was a web developer building mobile apps using one codebase!

Despite my enthusiasm, I quickly ran into issues that would continue to haunt me over time.

Limited cross-platform deployment: I wanted to make my apps available on iOS, Android, and the web. Cordova’s focus on mobile, as well as limited browser APIs, made it challenging, if not impossible, to reach all platforms successfully.
Opaque native configuration: Builds would fail or features wouldn’t work as expected, and I struggled to solve them since I didn’t understand Cordova’s native project abstractions.
Stability: I dreaded updating the apps because native plugins would constantly break between new mobile OS versions or conflicting plugin versions.

Those were dark times. However, I’ve recently been building a new Real App™️ using Capacitor and well, it’s made me fall in love with mobile all over again. In this post, I’ll cover how Capacitor solves all of these issues, including cross-platform support, easy native configuration, long-term stability, and the built-in Cordova migration support.

Side-note: If you’re not already familiar with Capacitor, you can find a ton of info here and here. TL;DR - it’s a new native runtime for building cross-platform mobile, desktop, and web apps, built by the Ionic team. You can think of it as a spiritual successor to Cordova that applies many hard-earned lessons from the last 10 years of hybrid mobile development.

And now, let’s review how Capacitor applies those lessons, resulting in a much-improved developer experience.

Beyond Mobile

Cordova’s focus on mobile, coupled with limited web browser APIs, made it challenging, if not impossible, to reach all platforms with a single codebase successfully.

Recognizing this, Capacitor embraces a web-first approach with its Core APIs, meaning they work on the web, iOS, Android, and desktop. Since they provide access to commonly needed functionality, they cover much of the core Cordova plugins while also including some new features.

The Capacitor Camera API is a great example. With a single method call, you can take a photo with the device’s camera on the web, iOS, and Android:

import { Plugins, CameraResultType } from '@capacitor/core';
const { Camera } = Plugins;

async takePicture() {
  const image = await Camera.getPhoto({
    quality: 90,
    resultType: CameraResultType.Uri
  });

  imageElement.src = image.webPath;
}

That said, what about features that aren’t available on the web? In those cases, web plugins can be built to act as a fallback. When in doubt, check Can I Use to see what’s possible.

Additionally, I was thrilled to learn that browser APIs have evolved to become more feature-rich since I began building hybrid apps years ago. As you can see from my favorite reference site, What Web Can Do Today, device integration is more powerful than ever. Everything from Bluetooth to offline storage to virtual/augmented reality is available today.

Pairing Capacitor with these new browser APIs, I could build my app quickly in the browser like before, while also ensuring true cross-platform deployment.

Easy Native Project Configuration

Cordova leverages a single configuration file that abstracts away native project details from the developer, which is great for managing all of your configurations together. However, when project builds fail or features don’t work as expected, it’s difficult to understand what the issue is and where it’s occurring (is it Cordova tooling or native project code?) since any applied changes are a black box to web developers. As a result, it’s too easy to get stuck on a problem completely unrelated to app development.

Capacitor takes the opposite approach, fully embracing configuration via native IDEs. There are two steps to implementing a native mobile feature with Capacitor: configuring the native project and handling the feature “the Capacitor way” within the app’s code.

Native Project Management

I’ll admit that I was initially skeptical about Capacitor’s approach to native project management. Despite Cordova's issues, I liked having a single configuration file to manage my native iOS and Android projects. Moving to Capacitor meant managing the native projects myself. Naturally, this was intimidating because I thought the whole point of the hybrid app approach was to avoid learning native app development. How much time would this take to learn? Ugh.

After trying it though, I was pleasantly surprised. Despite being only somewhat familiar with the native IDEs (Xcode and Android Studio), it turns out that the learning curve is quite small. You can go as shallow or deep into them as needed. Most of the time you just make small manual changes to AndroidManifest.xml (Android) or Info.plist (iOS).

When implementing complex mobile features (think: deep links, OAuth), you research the topic (example: “ios deep links” leads you to Apple’s docs) and follow the exact steps from the official documentation. Unlike Cordova, which abstracts these details away from you, features are implemented using the same instructions a native developer follows.

Implementing Features

Once configuration is complete, implementing the feature “the Capacitor way” isn’t all that challenging or “custom.” Depending on the use case, this could mean using a Capacitor Core API, a community plugin, or simply regular code. The effort varies, but generally, it’s straightforward.

As a bonus, if you do learn native mobile development someday (or build a Capacitor plugin), you’ll be better prepared because you understand the native ecosystem already.

Regardless of which cross-platform solution you choose, you have to learn mobile concepts anyway. Why not learn them the right way?

Stability

While we usually look forward to new software features and improvements, I dreaded updating my Cordova apps. Native plugins would constantly break between new mobile OS versions and conflicting plugin versions would mean I could update one plugin but not the other. Without a native development background, I got stuck often, forced to post on online forums and just hope for an answer.

While Capacitor doesn’t fully resolve the above challenges, it does a great job of equipping you to handle them. After just a bit of time developing apps with Capacitor, I feel more confident implementing features directly in each native project, as well as in Capacitor’s long-term stability as well.

Given that Capacitor gives you full control over native project management, many native features don’t require a plugin anymore (like deep linking - new guide coming soon!), so app size is reduced and performance is improved. Less code to maintain (especially if it’s not yours!) is a huge plus.

Also, most app features are configured once, then never touched again. And, given Apple and Google’s strong attention to backward compatibility, it could be years (if ever) before you need to make changes.

When you do run into issues while developing an app, it’s easy to search online for the answer. With no abstraction layer in place, you can search for and follow the answer as a native developer would. Personally, I feel much more confident in my ability to make changes and not get stuck.

Migration: Moving from Cordova to Capacitor

If by now you’re sold on giving Capacitor a try, you’ll be thrilled to learn that Capacitor has built-in Cordova migration support, designed to make the process as seamless as possible. Here’s a sampling of what it offers.

When you add a new platform (iOS, Android, etc.) to the project, a warning appears if an incompatible plugin is found. Most of the time, this is because Capacitor has an equivalent core plugin, or it simply isn’t needed anymore. Here’s cordova-plugin-splash-screen after running ionic cap add ios for example:

Found 1 incompatible Cordova plugin for ios, skipped install
cordova-plugin-splashscreen (5.0.2)

Also, if you install additional Cordova plugins at any time, then sync the project (this updates the native platforms and their dependencies), Capacitor tells you what you need to do with Cordova plugins that are supported but need additional native project configuration. Here’s the deep links plugin warning, for example:

$ ionic cap sync
[warn] Plugin @ionic-enterprise/deeplinks might require you to add

    <dict>
      <key>CFBundleURLSchemes</key>
      <array>
        <string>$URL_SCHEME</string>
      </array>
    </dict>

in the existing CFBundleURLTypes entry of your Info.plist to work

Cordova preferences are migrated over, too. When Capacitor is added to an existing Cordova project, it reads the <preferences> in config.xml and brings them into capacitor.config.json. You can manually add more preferences to the cordova.preferences object, too.

// capacitor.config.json
{
  "cordova": {
    "preferences": {
      "ScrollEnabled": "false",
      "android-minSdkVersion": "19",
   }
}

This is just a sampling of how smooth the migration process is. See complete migration details here.

We’ve come a long way since I started building hybrid mobile apps years ago. These days, I’m more productive than ever and loving mobile development again.

What’s been your experience with Capacitor been like so far? Let us know in the comments below. If you haven't tried out Capacitor yet and you’d like to give it a try, check out our new tutorial here.