Skip to content

Latest commit

 

History

History
206 lines (106 loc) · 11.5 KB

README.md

File metadata and controls

206 lines (106 loc) · 11.5 KB
Raw

Wix App Template: Custom Shipping Rates

The Custom Shipping Rates app template is part of the Wix app templates collection.

This Next.js 14 template demos a simple shipping solution, is fully customizable and sets a foundation for developing self-hosted Wix apps. It takes care of webhooks and OAuth, implements a Wix SPI and features a pre-built dashboard page, designed with the Wix Design System and built with the Wix Dashboard SDK.

The template handles common app functionalities, laying the groundwork for further customization and development.

About Wix app templates

Wix apps enhance the functionality of Wix sites by adding new features such as custom pages, dashboard components, third-party integrations, or site analytics. Starting with an app template fast-tracks the development process, providing a working foundational app that developers can modify and build upon. This approach saves valuable time, allowing for a quick transition from concept to a fully functional app.

Learn more about Wix app templates and explore our growing template collection.

Template features

This Wix app template incorporates the following features:

  • Self-hosting: Develop and host an app on any platform, and integrate with Wix using the Wix Dev Center.
  • OAuth: Secure authentication flow following Wix's guidelines.
  • Wix Design System: Utilize Wix's reusable React components for a cohesive user experience.
  • Wix Dashboard SDK: Integrate custom dashboard components with the Wix site dashboard.
  • Shipping Rates SPI: Integrate custom logic for calculating shipping rates.
  • Webhooks: Pre-configured to handle app lifecycle events.

Quick deployment on Vercel or Netlify

This template supports quick deployment on Vercel or Netlify, automating the setup process to get your app running with minimal configuration. To clone the repo and get the app up and running on Vercel or Netlify in minutes, go to the app template page and follow the instructions there.

Quick deployment on a different platform

To deploy on any other platform, follow these steps:

Step 1 | Deploy the app's server code

Follow your platform's instructions to clone the repo and deploy the app server, then find and copy the deployment domain. This is the base URL for your app's server.

Step 2 | Create an app in the Wix Dev Center

To generate an app in the Wix Dev Center and pre-configure it automatically for the template:

  1. Go to the app template page and click Use Template.

  2. Under Select your hosting service, select Deploy somewhere else, then click Continue.

  3. Under App name, enter a name for your app. For example: "Custom Shipping Rates".

  4. Under Base URL, enter the base URL for your deployment.

  5. Click Create & Continue.

This creates an app for you in the Wix Dev Center with the required URLs and permissions pre-configured.

Step 3 | Configure environment variables

Once your app is created, a screen appears with environment variables you need to copy to your app code:

  • WIX_APP_ID: Your app's Wix App ID.
  • WIX_APP_SECRET: Your app's secret key.
  • WIX_APP_JWT_KEY: Your app's public key.

Save these environment variables in your app code and redeploy the app. When deployment is finished, your app is ready to install.

Step 4 | Test the app

Follow these steps to create a development site, install your app on the site, and try it out.

  1. In your app's page in the Wix Dev Center, click Test Your App in the top right, then click Create Development Site.

  2. In the list of business solutions to install on the development site, click Wix Stores, then click Create Site.

  3. Back in your app's page in the Wix Developers Center, click Test Your App, then click App Market Website.

  4. Click Add to Site.

  5. Click Select next to the development site you just created.

  6. Wix now requests the site permissions your app requires. Click Agree & Add to install the app.

Your app is now installed on your development site. To see the app's dashboard page, click Apps in the site dashboard's left sidebar, then click Custom Shipping Rates.

What quick deployment gives you

When you deploy this template, an app is automatically created for you in the Wix Dev Center, pre-configured with settings required for the app to function properly within the Wix ecosystem. Find these pre-configured settings later in the app's dashboard as follows:

When your server is deployed you can also preview the app's site dashboard page UI by navigating in the browser to <YOUR_BASE_URL>/dashboard.

Local deployment

While developing your app, you may also wish to deploy and test it locally. You can do this as follows:

  1. Clone your version of the app repo locally:

    git clone <YOUR_REPO>

  2. Make sure you are in the repo's root folder, then install dependencies:

    npm install

  3. Create a file called .env.local in the repo's root folder. In that file, paste the required environment variables that you copied during quick deployment.

    If you didn't copy these values during quick deployment, you can retrieve them in the Wix Dev Center, then paste them in the following format:

    # App ID and App Secret Key: Retrieve from the OAuth page in the app's dashboard in the Wix Dev Center.
APP_ID=<APP_ID>
APP_SECRET=<APP_SECRET KEY>

# App Public Key: Retrieve from the Webhooks page in the app's dashboard in the Wix Dev Center.
WEBHOOK_PUBLIC_KEY="<APP_WEBHOOK_PUBLIC_KEY>"

    Note: Always keep your .env.local secure and never commit it to version control. This file contains sensitive keys that should not be exposed publicly.

  4. For the URLs configured in the Wix Dev Center, replace the app's base URL with https://localhost:3000/:

    • OAuth page: App URL and Redirect URL for the app OAuth flow.

    • Webhooks page: App Removed and App Installed webhooks.

  5. To start the development server, enter:

    npm run dev

You can now install the app on a Wix site with server code running locally.

Note: Remember to revert to the deployment URLs in the Wix Dev Center when you are ready to switch your app to production server deployment. You'll need to reinstall the app for the change to take effect.

Extend and customize the app

The template is designed for easy customization and extension. Here are some suggested entry points where you can add your own custom logic or functionality:

Dashboard page customization

The dashboard page is pre-integrated with the Wix Design System and Wix Dashboard SDK, providing a simple user interface that includes support for server-side rendering. It includes navigation to other relevant pages and an example of a shipping delivery form, and it utilizes the Wix Data API to query and present the last three orders in the dashboard. It utilizes both client-side and server-side SDK implementations.

Customize the dashboard page to fit your specific needs, whether it's updating the UI or adding new features.

Development entry point: src/app/dashboard/page.tsx

This file contains the parent component for the dashboard interface. The interface uses the app model defined in src/app/types/app-data.model.ts to provide an array of shipping delivery methods. It's a prime location for extending the dashboard functionality or integrating additional services.

Integrate the app with an external database

This template does not include database persistence. Instead, it's designed to be easily integrated with your choice of database solutions for storing app data.

Development entry point: src/app/actions/app-data.ts

This file contains shell functions you can extend with functionality for saving and retrieving data using an external database.

Shipping Rates SPI implementation

The app leverages the Wix eCommerce Shipping Rates SPI to incorporate a basic shipping rate customization functionality based on item weight or quantity. This implementation provides a flexible framework that you can extend to provide more tailored shipping options.

Development entry point: src/app/api/shipping-rates/v1/getRates/route.ts

This endpoint is crucial for customizing the logic used to calculate shipping rates. The implementation can be extended or refined to accommodate different logistics models, alternative calculation criteria, or integration with third-party shipping APIs.

Webhooks support

The template implements support for two app lifecycle webhooks.

Development entry points:

In these files, you can extend the logic that is triggered when the app is installed or uninstalled. For example: add custom cleanup logic, notification systems, or integration with external services upon app installation or removal.

You can also add routes to support additional webhooks, basing your implementation on the patterns modelled here.

Learn more

For more information: