{"id":23318285,"url":"https://github.com/cumulocity-iot/cumulocity-sample-react-library","last_synced_at":"2025-08-22T17:31:08.425Z","repository":{"id":81495054,"uuid":"403947797","full_name":"Cumulocity-IoT/cumulocity-sample-react-library","owner":"Cumulocity-IoT","description":"A sample react library which fetches and displays the device details based on the device id.","archived":true,"fork":false,"pushed_at":"2021-12-02T13:41:54.000Z","size":314,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-07T04:53:58.835Z","etag":null,"topics":["client","cumulocity-client","cumulocity-iot","iot-analytics","react"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cumulocity-IoT.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-07T11:12:04.000Z","updated_at":"2024-10-09T11:03:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"66373dae-7ae4-4b35-a23f-2a2f017c6052","html_url":"https://github.com/Cumulocity-IoT/cumulocity-sample-react-library","commit_stats":null,"previous_names":["cumulocity-iot/cumulocity-sample-react-library"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Cumulocity-IoT/cumulocity-sample-react-library","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fcumulocity-sample-react-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fcumulocity-sample-react-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fcumulocity-sample-react-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fcumulocity-sample-react-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cumulocity-IoT","download_url":"https://codeload.github.com/Cumulocity-IoT/cumulocity-sample-react-library/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fcumulocity-sample-react-library/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271673565,"owners_count":24800717,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-22T02:00:08.480Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","cumulocity-client","cumulocity-iot","iot-analytics","react"],"created_at":"2024-12-20T17:16:30.171Z","updated_at":"2025-08-22T17:31:06.226Z","avatar_url":"https://github.com/Cumulocity-IoT.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\n\n\n\n#  React Library Project[\u003cimg width=\"35\" src=\"https://user-images.githubusercontent.com/67993842/97668428-f360cc80-1aa7-11eb-8801-da578bda4334.png\"/\u003e](https://github.com/SoftwareAG/cumulocity-sample-react-library/releases/download/1.0.0/sample-react-library-1.0.0.tgz)\n\n The react library project is a sample library created using ReactJS. It  fetches the Inventory data  by taking the device id as an input and displays the same in UI. It also updates the device name by taking an input from the user.\n This widget library can be used in react and angular applications.\n\n## Build Instructions \n\n| Serial No.       | Scenario         | Instruction Link  |\n| ------------- |:-------------:| -----:|\n|1|If you want to directly use the react widget library in cumulocity| [Click here](https://github.com/SoftwareAG/cumulocity-react-runtime-widget.git)\n| 2     | If you want to directly use the react widget library in a react app | [Click here](#Instructions-to-directly-use-the-react-widget-library-in-a-react-app) |\n| 3     | If you want to extend/modify this widget library and use it in your application     |  [Click here](#Instructions-to-extend-or-modify-the-react-widget-library-and-use-it-in-your-react-app) |\n| 4 | If you want to create the custom react library from scratch     |    [Click here](#Instructions-to-create-the-custom-react-widget-library-from-scratch) |\n\n\n### Instructions to directly use the react widget library in a react app\n\n1. Follow the instructions to create a react app [here](https://github.com/SoftwareAG/cumulocity-sample-react-app)\n2. After creating a react app, if you have npm account, you need to install the react library package into your project. Run the below command to do the same.\n\t```\n\tnpm i sample-react-library-widget\n\t``` \n3. If you do not have npm account, then download the binary file from the download icon above and place it under any folder(example: binary) in your react app. Install this \t    binary file in your project.\n\t``` \n\tnpm i ./path/binary-file-name\n\tExample: npm i ./binary/sample-react-library-1.0.0.tgz\n\t```\n\t\n4. We need to add a block of code in App.tsx file to authenticate the user on cumulocity platform so that our library can consume inventory apis.\n\n\t#### Add the below block of code\n\n\n\t\t\n\t\timport { BasicAuth, Client } from  \"@c8y/client\";\n\t\timport { FetchDeviceDetails } from  \"sample-react-library-widget/lib\";\n\n\n\t\tfunction  App() {\n\t\tconst  auth = new  BasicAuth({\n\t\tuser:  'username',\n\t\tpassword:  'password',\n\t\ttenant:  'tenantId'\n\t\t});\n\n\t\tconst  client = new  Client(auth, 'tenantUrl');\n\t\tclient.setAuth(auth);\n\t\tconst  fetchClient = client.core;\n\n\t\treturn (\n\t\t\u003cdiv\u003e\n\t\t\u003cFetchDeviceDetails  fetchClient = {fetchClient}  id={'deviceId'}\u003e\u003c/FetchDeviceDetails\u003e\n\t\t\u003c/div\u003e\n\t\t);\n\t\t}\n\n\t\texport  default  App;\n\t\t\n \n5. Run the below command to see the installed react widget library.\n\t```\n\t npm run start \n\t ```\n\n\t **NOTE:**  The fetchClient and device id will be passed as an input from react app into the react widget library as below:\n\t  *\u003cReact-Library-Name  fetchClient = {fetchClient}  id={'deviceId'}\u003e\n\t  \u003c/React-Library-Name\u003e*\n \n### Instructions to extend or modify the react widget library and use it in your react app\n \n####  Requirements:\n - Git\n -  NodeJS (release builds are currently built with  `v14.15.0`)\n - NPM(Included with NodeJS)\n\n#### Instructions\n\n 1. Clone the repository:\n\n\t``` git clone https://github.com/SoftwareAG/cumulocity-sample-react-library.git```\n\n2. Change the directory:\n\n\t```cd  cumulocity-sample-react-library ```\n\n3. Install the dependencies:\n\n\t``` npm install ```\n\n4. Modify the code according to your use case.\n5. #### You have 2 options once your library is ready\n\t- If you have an account on npm, You can publish the react library with the below steps.\n\t\t- Add a build script in package.json file.\n\t\t\t```\n\t\t\t\"scripts\": {\n\t\t\t\"build\": \"tsc -p .\"\n\t\t\t}\n\t\t\t```\n\t\t-\tRun the below command to create a build.\n\t\t\t``` \n\t\t\tnpm run build\n\t\t\t```\n\t\t- Run the below command and enter your npm account credentials.\n\t\t\t```\n\t\t\tnpm publish\n\t\t\t```\n\t- If you do not want to publish your library on npm , you can create .tgz file with below steps.\n\t\t- Add a build script in package.json file.\n\t\t\t```\n\t\t\t\"scripts\": {\n\t\t\t\"build\": \"tsc -p . \u0026\u0026 copy package.json lib \u0026\u0026 cd ./lib \u0026\u0026 npm pack\"\n\t\t\t}\n\t\t\t```\n\t\t - Run the below command and a .tgz file will be created in 'lib' folder.\n\t\t\t```\n\t\t\tnpm run build\n\t\t\t```\n\t\t\tAll the generated assets will be put into lib folder and a .tgz file will be created.\n\t\t\t\n\t**Note:** Till this point you have created a react widget library. You can now install it in your react app by following the below instructions.\n\n6.  Follow the steps to create a react app from [here](https://github.com/SoftwareAG/cumulocity-sample-react-app). \n7. Follow the steps to install the react library you just developed in your react app [here](#Steps-to-install-the-react-widget-library-in-a-react-app)\n8. After you have installed the react widget library in your react app, add the code and modify according to the requirement of the library you just developed [here](#Add-the-below-block-of-code) .\n\n### Instructions to create the custom react widget library from scratch\n\n#### Execute below commands to setup New React Library Project for widget development. \n\n 1. Create a folder with any name of your choice.\n \n    ```(example: react-library)```\n\n 2. Navigate inside the folder and initialise a new package.json with default options.   \n\n    ```npm init -y```\n\n 3. As we have to use typescript, react and types in react component, we will install them as a dev dependencies.\n\n     ``` npm i typescript -D```\n     \n     ```npm i react @types/react -D```\n     \n\t   You will see the following entries in package.json file.    \n\t   \n\t\"devDependencies\": {\n\t              \"@types/react\": \"^17.0.19\",\n\t                react\": \"^17.0.2\",\n\t              \"typescript\": \"^4.4.4\"\n\t              } \n              \n  \t**NOTE:** *We install react, typescript and types as dev dependency because we do not want to fix a particular version of them for consumer of our package.*\n\n 4. Install typescript compiler to initialise a new tsconfig file.\n\n\t  ```npx tsc --init```\n\t  \n5.  In tsconfig file, we will enable: \n declaration,declarationMap, sourceMap,outDir: \"lib\" and  jsx: \"react\".\n \"compilerOptions\": {\n\t\t\t\t\t\"jsx\": \"react\",\n\t\t\t\t\t\"target\": \"ES2015\",\n\t\t\t\t\t}\n\t\t\t\t\t\n\t```  \n\tdeclaration:To publish build version of our project\n\tdeclarationMap:To navigate from d.ts file to ts file\n\tsourceMap:To observe our ts file from js file.\n\toutDir:To generate our output declaration,declarationMap,sourceMap file in lib folder.\n\tjsx: point it to react to enable react support within typescript\n\t```\n\n 6. Since we are using typescript, we will add  \"types\" in package.json that will point to \"lib\" folder.\n\t````\n\t \"name\": \"react-library\",\n\t     \"version\": \"1.0.0\",\n\t     \"description\": \"A react library which fetches the device details of a particular device id. It also updates the device name by taking an input from the user.\",\n\t\t \"main\": \"index.js\",\n\t     \"types\": \"lib\",\n\t````\n\n \n 7. Add the following as peer and dev dependencies in package.json file.\n\n\t\t\t\"peerDependencies\": {\n\t\t\"react\": \"\u003e=17.0.2\",\n\t\t\"@c8y/client\": \"^1009.0.19\",\n\t\t\"moment\": \"^2.29.1\",\n\t\t\"react-query\": \"^3.21.1\",\n\t\t\"styled-components\": \"^5.3.0\"\n\t\t},\n\n\t\t\"devDependencies\": {\n\t\t\"@types/react\": \"^17.0.19\",\n\t\t\"react\": \"^17.0.2\",\n\t\t\"typescript\": \"^4.4.4\",\n\t\t\"@types/styled-components\": \"^5.1.10\",\n\t\t\"react-query\": \"^3.21.1\",\n\t\t\"@c8y/client\": \"^1009.0.19\",\n\t\t\"moment\": \"^2.29.1\",\n\t\t\"styled-components\": \"^5.3.0\"\n\t\t},\n\t**NOTE:** *We add a peer dependency so that when we install a package, npm know that it has to install some version of react which is \u003e= 17.. or so.* \n\n8. Create **src/index.tsx** file as entry point for our library.(*tsx allows us to use jsx*).\n\tAll our input typescript code will be located in **src** folder. \n9. In package.json, \"main\": will contain entry point of our library which in our case will be \"lib/index.js\". \n\n10. In order to use Cumulocity Inventory Service, we need to install c8y/client in our library project.\n\n\n\t\tnpm i @c8y/client@1009.0.19\n\n11. In order to use react query in our library, we need Query Client.\n\t\t\t```\n\t\t\tnpm i react-query\n\t\t\t```\n\n\tYou will see the following entry in package.json file.\n\t```\n\t\"dependencies\": {\n\t\"@c8y/client\": \"^1009.0.19\",\n\t\"react-query\": \"^3.21.1\"\n\t}\n\t```\n12. The basic setup to start developing react widget is ready. You can develop the widget according to your use case.\n13. After developing the react widget, build the react library and install it in your react app [here](#You-have-2-options-once-your-library-is-ready).\n\n#### How to use Cumulocity Inventory APIs in react widget  library\n\nIn order to use cumulocity inventory apis, you need to pass fetchClient object to your react widget library.\n\nBelow are the examples of how you can use cumulocity inventory apis in your react widget library to fetch and update device details. \n\n 1. Provide id and fetchClient object as an input to react library.\nAdd the below block of code in index.tsx file and do the necessary import.\n\t```\n\t\timport { FetchClient } from  \"@c8y/client\";\n\t\timport { QueryClient } from  \"react-query\";\n\n\t\t\ttype  Props = {\n\t\t\tfetchClient:FetchClient;\n\t\t\tid: string;\n\t\t\t}\n\n\t\tconst  client = new  QueryClient();\n\t```\t\t\n\n2. Create a functional Component 'src/App.tsx' . App.tsx will receive fetchClient and device id as input. Therefore create props for the same.\n\t```\n\t\timport { FetchClient } from  \"@c8y/client\";\n\t\timport  React from  \"react\";\n\t\t\n\t\t type  Props = {\n\t\tfetchClient:FetchClient;\n\t\tid: string;\n\t\t}\n\n\t\tconst  App: React.FC\u003cProps\u003e = ({fetchClient, id}) =\u003e {\n\t\treturn(\n\t\t\u003cdiv\u003e\n\t\t\u003cdiv\u003eThis is a demo widget which fetches the device details \u003c/div\u003e\n\t\t\u003c/div\u003e\n\t\t);\n\t\t}\n\t\texport  default  App; \n\t\t```\n\n3. In index.tsx, Create a functional component and pass fetchClient and device id as an input.\nThese inputs will inturn be passed as inputs to our App functional component.\n \n\t ```\n\t const  client = new  QueryClient();\n\t export  const  FetchDeviceDetails : React.FC\u003cProps\u003e = ({fetchClient, id}) =\u003e{\n\treturn (\n\t\u003cQueryClientProvider  client={client}\u003e\n\t\u003cApp  fetchClient={fetchClient}  id={id}  \u003e\u003c/App\u003e\n\t\u003c/QueryClientProvider\u003e\n\t)\n\t}\n\t```\n\t**NOTE:**  Wrap the App component inside QueryClientProvider to enable it to use Query Client.\n\n4. In App.tsx file, create an interface of Device Item to map the device details.\n\t```\n\texport  type  DeviceItem = {\n\tid:string;\n\tcreationTime: string;\n\tlastUpdated:string;\n\tname: string;\n\t}\n\t```\n\n5. In App.tsx, add the following methods to get and update device details.\n\n\tGet Device Details\n\t```\n\tconst  inventory = new  InventoryService(fetchClient);\n\tconst  getDeviceDetails = async (): Promise\u003cDeviceItem\u003e =\u003e\n\t((await  inventory.detail(id)).data) as  any;\n\tconst {data, refetch} = useQuery\u003cDeviceItem\u003e('devices', getDeviceDetails);\n\t```\n\n\tUpdate Device name\n\t```const  updateDeviceDetails = async (name: any) =\u003e {\n\tconst  partialUpdateObject: Partial\u003cIManagedObject\u003e = {\n\tid:  id,\n\tname:  name,\n\t};\n\tinventory.update(partialUpdateObject).then((result) =\u003e{\n\tif(result.res.status == 200) {\n\trefetch();\n\t}\n\t});\n\t```\n\n### Steps to install the react widget library in a react app\n\n- If you have published the react widget library on npm, then you can run the below command to install it in your react app.\n\t```\n\tnpm i react-library-name\n\t```\n- If you have created a .tgz file, then you can run the below command to install it in your react app.\n\n\t- Create a folder in your application(example: binary) and place the copied .tgz file from react library into this folder.\n\n\t- Run the below command to install the react widget library.\n\t\t```\n\t\tnpm i ./binary/react-library-file-name.\n\t\tExample:  npm i ./binary/sample-react-library-widget.1.0.6.tgz\n\t\t``` \n\n---\nThis library is provided as-is and without warranty or support. They do not constitute part of the Software AG product suite. Users are free to use, fork and modify them, subject to the license agreement. While Software AG welcomes contributions, we cannot guarantee to include every contribution in the master project.\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcumulocity-iot%2Fcumulocity-sample-react-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcumulocity-iot%2Fcumulocity-sample-react-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcumulocity-iot%2Fcumulocity-sample-react-library/lists"}