npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

khoros-aurora-sdk

v24.10.0

Published

The Aurora SDK allows you to customize various plugin points using a Git repository for your community. You can preview changes made to the repository through Aurora's Plugin Preview tool, which uses Node to synchronize your local development environment

Downloads

1,964

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Maintainers

deepaks92deepaks92akash.goenkaakash.goenkadolan.halbrookdolan.halbrook

Keywords

Khoros_Aurora_SDKKhoros_Community_Aurora_SDKAurora_SDKAurora_Dev

Readme

Using the Aurora SDK

The Aurora SDK is a set of tools and libraries that allow you to build custom components and endpoints for your community. This document will guide you through setting up your development environment and using the SDK to build custom components and endpoints.

Prerequisites

Start by ensuring you have NodeJS installed. Node versions 18 and newer are currently supported. Using NVM (https://github.com/nvm-sh/nvm) will make it easier to use newer versions of NodeJS in the future. If you have NVM installed, simply run nvm use in the terminal to ensure you're using the correct version of NodeJS.

Once NodeJS is installed, open a terminal shell, and run npm i from this directory . This will ensure the necessary dependencies are available, including the Aurora SDK.

Setting up the environment

  1. In a text editor, edit the .env.local file in the root your plugin's filesystem. If you don't see it, note that the file may be hidden by default by your OS (Mac: https://www.macworld.com/article/671158/how-to-show-hidden-files-on-a-mac.html, Windows: https://support.microsoft.com/en-us/windows/view-hidden-files-and-folders-in-windows-97fbc472-c603-9d90-91d0-1166d1d9f4b5). If you still don't see this file, create it.
  2. Add an entry for LIA_URL. This is the base URL of your community (for example, LIA_URL=https://community.bigco.com)
  3. Add an entry for SDK_KEY to be the value of the SDK Key found in the Dev Tools (/admin/dev) section of your community's admin console (for example, SDK_KEY=abcd1234)
  4. Save your changes to the .env.local file.

Using Plugin Preview

Plugin Preview synchronizes the assets in your plugin with your community. The changes are kept in memory and are only visible to admin users.

  1. Open a terminal shell, and run npm run start. This will start the Plugin Preview process.
  2. Wait for the initial Plugin Preview sync to finish before attempting file changes. You should see a message like the following once the initial sync is finished: INFO (PluginPreview/74899): Watching for plugin repo changes.
  3. At this point, any changes you make to the files in your plugin repository will be synchronized with your community. As a logged-in user, reload the page in the community where the asset is used to see the changes. To undo the changes, revert the file you changed.
  4. On Plugin Preview startup, any currently changed files are synced into memory. These changes are cleared from memory once the Plugin Preview process is stopped. The process can be stopped using Ctrl-C.

Developing a Custom React Component

  1. Set up your SDK environment and ensure you have Plugin Preview configured correctly.
  2. If it doesn't exist already, copy over the src/components/ReactComponent directory from https://github.com/community-khoros/aurora-plugin-example to your plugin's filesystem.
  3. Commit and push these changes to a branch of your plugin of your choosing.
  4. Create a pull request to pull these changes into the main branch of your plugin (<phase>-main, not main).
  5. Once the pull request is merged, in a browser, go to Designer in the admin console of your community.
  6. From there, go to "Page Templates" and select the page where you want to add the custom component.
  7. Click on the "+" symbol to add the component, then select "Custom" under "Other".
  8. Select "ReactComponent". This will add a simple React component to your page's quilt.
  9. Click Save and Publish.
  10. In the browser, navigate to the page where the component was published.
  11. In a new terminal shell, run npm run start. This will start the Plugin Preview process. The process can be stopped using Ctrl-C.
  12. Wait for the initial Plugin Preview sync to finish before the custom components will be available. You should see a message like the following once the initial sync is finished: INFO (PluginPreview/74899): Watching for plugin repo changes.
  13. In your browser, reload the page with the component . The sample React component should now load from your local dev server (http://localhost:3002).
  14. Edit the src/components/ReactComponent/Component.tsx file.
  15. In your browser, reload the page with the component. Your changes should be reflected on the component.
  16. All changes are cleared once the dev process is stopped. Also note that the temporary changes are only visible while you are logged in.
  17. To continue development on a separate branch, create a new branch of your plugin from qa-main.
  18. Once this is done, you can safely remove the custom component from the page where it was added using Designer. It will still appear on the page as long as you specify your branch as the Active Branch in Dev Tools (/admin/dev in your community).

Developing a Custom Endpoint

  1. Set up your SDK environment and ensure you have Plugin Preview configured correctly
  2. If it doesn't exist already, copy over the src/endpoints/CatFact directory from https://github.com/community-khoros/aurora-plugin-example to your plugin's filesystem.
  3. In a new terminal shell, run npm run start. This will start the Plugin Preview process. The process can be stopped using Ctrl-C.
  4. Wait for the initial Plugin Preview sync to finish before attempting changes to the custom endpoint. You should see a message like the following once the initial sync is finished: INFO (PluginPreview/74899): Watching for plugin repo changes.
  5. Any changes you make to a custom endpoint will be synchronized to the specified Aurora instance.
  6. At this point you should be able to call the endpoint at https://<community-url>/endpoints/<endpoint-id> as a logged-in user (if viewing in a browser as a GET request).
  7. If you are making a non-GET request to the endpoint from a client like Postman you will need to add the SDK key to the request using the kh-aurora-sdk-key header
  8. Commit and push these changes to a branch of your plugin of your choosing
  9. Create a pull request to pull these changes into the main branch of your plugin (<phase>-main, not main)
  10. Once the pull request is merged, your endpoint changes should be available within five minutes.
  11. See the developer documentation in the Dev Portal for more information on how to write and call an endpoint.

Viewing Logs for your custom Endpoints

The endpoint context provides you with a logging mechanism you can use the log messages, which can be viewed by Khoros Support, Services and Engineering teams.

On your stage site, you can use the SDK to view log messages as they are logged (in real-time) for your custom endpoint.

To view the logs for your custom endpoint, follow these steps:

  1. Make sure you have the following environment variables set in your .env.local file:
    1. LIA_URL - The base URL of your community (for example, LIA_URL=https://community.bigco.com)
    2. SDK_KEY - The value of the SDK Key found in the Dev Tools (/admin/dev) section of your community's admin console. (for example, SDK_KEY=abcd1234)
  2. Open a terminal shell, and run npm run start:logger to start the Plugin Logger process.
  3. You should see some messages about it connecting to the plugin logging server:
[14:06:43.438] INFO (loggerClient/75084): Starting up plugin logging client...
[14:06:43.438] INFO (loggerClient/75084): Plugin logging client started.
[14:07:21.483] INFO (loggerClient/75084): Connected to aurora plugin logging server

Sometimes your stage site may be in the process of restarting or being updated. When this happens, you will see messages about waiting to connect until it becomes available again:

[14:06:43.438] INFO (loggerClient/75084): Starting up plugin logging client...
[14:06:43.438] INFO (loggerClient/75084): Plugin logging client started.
[14:06:43.455] INFO (loggerClient/75084): waiting for connection to aurora plugin logging server...
[14:06:44.122] INFO (loggerClient/75084): waiting for connection to aurora plugin logging server...
[14:06:46.115] INFO (loggerClient/75084): waiting for connection to aurora plugin logging server...
[14:06:50.723] INFO (loggerClient/75084): waiting for connection to aurora plugin logging server...
[14:06:55.744] INFO (loggerClient/75084): waiting for connection to aurora plugin logging server...
[14:07:00.750] INFO (loggerClient/75084): waiting for connection to aurora plugin logging server...
[14:07:05.755] INFO (loggerClient/75084): waiting for connection to aurora plugin logging server...
[14:07:10.762] INFO (loggerClient/75084): waiting for connection to aurora plugin logging server...
[14:07:15.769] INFO (loggerClient/75084): waiting for connection to aurora plugin logging server...
[14:07:21.483] INFO (loggerClient/75084): Connected to aurora plugin logging server

If an update or restart happens while you are connected, you will see a message about the connection being terminated and then about waiting to reconnect:

[14:40:57.182] INFO (loggerClient/76948): connection lost, the site may be updating or restarting...
[14:40:58.460] INFO (loggerClient/76948): waiting for connection to aurora plugin logging server...
[14:41:00.389] INFO (loggerClient/76948): waiting for connection to aurora plugin logging server...
[14:41:05.392] INFO (loggerClient/76948): waiting for connection to aurora plugin logging server...
[14:41:10.396] INFO (loggerClient/76948): waiting for connection to aurora plugin logging server...
[14:41:15.399] INFO (loggerClient/76948): waiting for connection to aurora plugin logging server...
[14:41:20.402] INFO (loggerClient/76948): waiting for connection to aurora plugin logging server...
[14:41:25.406] INFO (loggerClient/76948): waiting for connection to aurora plugin logging server...
[14:41:30.410] INFO (loggerClient/76948): waiting for connection to aurora plugin logging server...
[14:41:35.414] INFO (loggerClient/76948): waiting for connection to aurora plugin logging server...
[14:41:40.418] INFO (loggerClient/76948): waiting for connection to aurora plugin logging server...
[14:41:45.627] INFO (loggerClient/76948): Connected to aurora plugin logging server
  1. Once the Plugin Logger process is started, you can view the logs for your custom endpoint in real-time. The logs will be displayed in the terminal window where the Plugin Logger process is running. If your custom endpoint logs any messages, you should see them in the terminal window: you should see a message like this one:
[14:44:22.985] INFO (endpoints|qa-main|Sample/76948): Handling request at /endpoints/Sample

Setting a temporary log level for your custom Endpoints

By default, the log level threshold for custom endpoints is set to INFO, which means logging at DEBUG and TRACE will not be shown. To change this, set ENDPOINTS_LOG_LEVEL in your .env or .env.local file before starting Plugin Preview and the log level will be set to the specified level when Plugin Preview starts up. It will be reset to the default level when Plugin Preview is stopped.

To set a temporary log level for a specific endpoint or module, set ENDPOINTS_LOG_LEVEL_OVERRIDES in your .env or .env.local file before starting Plugin Preview. The format is module=level where module is the name of the module

Example:

ENDPOINTS_LOG_LEVEL=debug
ENDPOINTS_LOG_LEVEL_OVERRIDES=EndpointManager=info endpoints|qa-main|CatFact=trace

Updating the SDK version

The major and minor version of the SDK dependency in your plugin's package.json file should match the major and minor version of the corresponding community. If they don't match, make sure to update the package.json file by running:

npm update khoros-aurora-sdk --save

This will update your SDK version to the latest release version. Make sure to commit and push this change to package.json (and package-lock.json if it exists).

Why is my Custom React Component or Endpoint not showing up on my community?

Both custom React components and custom endpoints are compiled code, and sometimes that code may fail to compile. The first step is to check out the repository, and in that repository, make sure the SDK is up-to-date (see [Updating the SDK Version](##Updating the SDK version)).

Once you have verified the SDK version is correct, try running npm run build and verify the build step passes. If it doesn't, correct any errors until it does.

Also, make sure all of your custom React components are referenced in the federation config. You can see this in the logging during the build step, for example:

[10:28:16.094] INFO (build/58444): Federation config is {"./PageContext":"./src/components/PageContext/PageContext.tsx","./CatFactToast":"./src/components/CatFactToast/CatFactToast.tsx","./CssModuleAndModal":"./src/components/CssModuleAndModal/CssModuleAndModal.tsx","./GraphQLQuery":"./src/components/GraphQLQuery/GraphQLQuery.tsx"}

or additionally, you can check the result by opening the generated federation.config.json file at the root of the plugin filesystem. All your custom React components should be referenced. If not, verify the component descriptor is valid and named <ComponentName>.component.json.

When you have ensured the build step is passing and all your custom components are referenced correctly in federation.config.json, commit and push your changes.

At this point you can make sure the build is passing in GitHub by check the "Actions" tab. There should be an action triggered when your changes are pushed to the repository. Make sure the result of the action is successful.

Extending the Next.js configuration

Custom React components are build using Next.js. If you need to extend the configuration (for example, adding additional packages to transpile), you can do so by implementing "next.overrides.js" and checking in the result. NOTE: changes to the Webpack configuration will be ignored.

Building Typescript types for GraphQL queries

By running npm run build:graphql (or simply npm run build), Typescript types will be built for any GraphQL queries or fragments. You can use these to strongly type query variables and results in custom React components and custom endpoints.

See the https://github.com/community-khoros/aurora-plugin-example repo for sample code on how to do this.