{"id":29138778,"url":"https://github.com/remoteoss/remote-flows","last_synced_at":"2026-05-04T13:02:03.103Z","repository":{"id":278556892,"uuid":"936005423","full_name":"remoteoss/remote-flows","owner":"remoteoss","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-01T18:47:06.000Z","size":11269,"stargazers_count":4,"open_issues_count":19,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-05-01T19:10:40.394Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://remote-flows-eight.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/remoteoss.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-20T11:28:10.000Z","updated_at":"2026-05-01T17:34:03.000Z","dependencies_parsed_at":"2025-03-06T15:23:10.223Z","dependency_job_id":"e3a74a6f-3c9c-4927-ab01-70c757a920bd","html_url":"https://github.com/remoteoss/remote-flows","commit_stats":null,"previous_names":["remoteoss/remote-flows"],"tags_count":127,"template":false,"template_full_name":null,"purl":"pkg:github/remoteoss/remote-flows","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remoteoss%2Fremote-flows","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remoteoss%2Fremote-flows/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remoteoss%2Fremote-flows/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remoteoss%2Fremote-flows/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/remoteoss","download_url":"https://codeload.github.com/remoteoss/remote-flows/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remoteoss%2Fremote-flows/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32608309,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"ssl_error","status_checked_at":"2026-05-04T10:08:02.005Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2025-06-30T14:11:20.054Z","updated_at":"2026-05-04T13:02:03.086Z","avatar_url":"https://github.com/remoteoss.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @remoteoss/remote-flows\n\n[![npm version](https://img.shields.io/npm/v/@remoteoss/remote-flows.svg)](https://www.npmjs.com/package/@remoteoss/remote-flows) [![Bundle Size](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/remotecom/b8884fb20051d4c0095a29569d51e34e/raw/remote-flows-bundle-size.json)](https://github.com/remoteoss/remote-flows/actions/workflows/update-badge.yml) ![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/remotecom/b94197caa302c8364afa820d9635cdf6/raw/remote-flows-coverage.json)\n\n\u003e **Note:** This badge reflects the latest published version. Check [npm](https://www.npmjs.com/package/@remoteoss/remote-flows) for current version information.\n\nA React library that provides components for Remote's embedded solution, enabling seamless integration of Remote's employment flows into your application.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Components API](#components-api)\n  - [RemoteFlows](#remoteflows)\n  - [Custom Field Components](#custom-field-components)\n- [Available Flows](#available-flows)\n- [Authentication](#authentication)\n- [Styling Options](#styling-options)\n  - [Using Default Styles](#using-default-styles)\n  - [Theme Customization](#theme-customization)\n  - [Custom CSS](#custom-css)\n- [Advanced Usage](#advanced-usage)\n- [Example](#example)\n- [Contributing](#contributing)\n- [Internals](#internals)\n\n## Installation\n\n```sh\nnpm install @remoteoss/remote-flows\n```\n\n## Quick Start\n\n```tsx\nimport { RemoteFlows, CostCalculator } from '@remoteoss/remote-flows';\nimport { defaultComponents } from '@remoteoss/remote-flows/default-components';\nimport '@remoteoss/remote-flows/styles.css';\n\nfunction App() {\n  const fetchToken = async () =\u003e {\n    const response = await fetch('/api/auth/token');\n    return response.json();\n  };\n\n  return (\n    \u003cRemoteFlows\n      components={defaultComponents}\n      auth={fetchToken}\n      environment='partners'\n    \u003e\n      \u003cCostCalculator onSuccess={(data) =\u003e console.log(data)} /\u003e\n    \u003c/RemoteFlows\u003e\n  );\n}\n```\n\n## Components API\n\n### RemoteFlows\n\nThe `RemoteFlows` component serves as a provider for authentication and theming.\n\n| Prop            | Type                                                                                          | Required | Deprecated | Description                                                                                                    |\n| --------------- | --------------------------------------------------------------------------------------------- | -------- | ---------- | -------------------------------------------------------------------------------------------------------------- |\n| `auth`          | `() =\u003e Promise\u003c{ accessToken: string, expiresIn: number }\u003e`                                   | No       | -          | Function to fetch authentication token. Optional when using cookie-based authentication via `credentials` prop |\n| `environment`   | `'partners' \\| 'production' \\| 'sandbox' \\| 'staging'`                                        | No       | -          | Environment to use for API calls (defaults to production)                                                      |\n| `theme`         | `ThemeOptions`                                                                                | No       | -          | Custom theme configuration                                                                                     |\n| `components`    | `Components`                                                                                  | No       | -          | Custom field components for form rendering                                                                     |\n| `proxy`         | `{ url: string, headers?: Record\u003cstring, string\u003e }`                                           | No       | -          | Configuration for API request proxy with optional headers                                                      |\n| `errorBoundary` | `{ useParentErrorBoundary?: boolean, fallback?: ReactNode \\| ((error: Error) =\u003e ReactNode) }` | No       | -          | Error boundary configuration to prevent crashes and show custom fallback UI                                    |\n| `debug`         | boolean                                                                                       | No       | -          | useful to see telemetry debugging in console                                                                   |\n| `credentials`   | `'include' \\| 'same-origin'`                                                                  | No       | -          | Credentials mode for fetch requests. Use `'include'` for cookie-based authentication without bearer tokens     |\n\n#### Error Boundary\n\nThe `errorBoundary` prop controls how the SDK handles runtime errors to prevent crashes in your host application.\n\n```tsx\n\u003cRemoteFlows\n  components={defaultComponents}\n  auth={fetchToken}\n  errorBoundary={{\n    useParentErrorBoundary: false,\n    fallback: (error) =\u003e (\n      \u003cdiv style={{ padding: '20px', textAlign: 'center' }}\u003e\n        \u003ch2\u003eSomething Went Wrong\u003c/h2\u003e\n        \u003cp\u003e{error.message}\u003c/p\u003e\n        \u003cbutton onClick={() =\u003e window.location.reload()}\u003eReload Page\u003c/button\u003e\n      \u003c/div\u003e\n    ),\n  }}\n\u003e\n  {/* Your flows */}\n\u003c/RemoteFlows\u003e\n```\n\n**Options:**\n\n- `useParentErrorBoundary` (boolean, default: `false`): If `true`, errors are re-thrown to your parent error boundary. If `false`, the SDK shows a fallback UI to prevent crashes.\n- `fallback` (ReactNode | function, optional): Custom UI to display when an error occurs. Only used when `useParentErrorBoundary` is `false`. Can be a React element or a function that receives the error object.\n\n**Behavior:**\n\n- When `useParentErrorBoundary: true` → Errors propagate to your application's error boundary\n- When `useParentErrorBoundary: false` without `fallback` → Shows default error message: \"Something went wrong in RemoteFlows. Please refresh the page.\"\n- When `useParentErrorBoundary: false` with `fallback` → Shows your custom fallback UI\n\n### Custom Field Components\n\nYou can customize form field components to match your application's design system.\n\n\u003e For detailed documentation on component customization including step-level and field-specific overrides, see the [Component Customization Guide](./docs/COMPONENT_CUSTOMIZATION.md).\n\n## Available Flows\n\nEach flow handles a specific Remote employment operation. For detailed API documentation, see the individual flow READMEs:\n\n- [**Cost Calculator**](./src/flows/CostCalculator/README.md) - Calculate employment costs for different countries\n- [**Onboarding**](./src/flows/Onboarding/README.md) - Onboard new employees\n- [**Contract Amendment**](./src/flows/ContractAmendment/README.md) - Modify existing employment contracts\n- [**Termination**](./src/flows/Termination/README.md) - Handle employee terminations\n\n## Authentication\n\nYou need to implement a server endpoint to securely handle authentication with Remote. This prevents exposing client credentials in your frontend code.\n\nYour server should:\n\n1. Store your client credentials securely\n2. Implement an endpoint that exchanges these credentials for an access token\n3. Return `access_token` and `expires_in` to the frontend application\n\nFor a complete implementation, check our [example server implementation](https://github.com/remoteoss/remote-flows/blob/main/example/server.js).\n\n### API Gateway Endpoints\n\n- **Development/Testing**: `https://gateway.partners.remote-sandbox.com`\n- **Production**: `https://gateway.remote.com/`\n\n## Styling Options\n\n### Using Default Styles\n\nImport the CSS file in your application:\n\n```css\n@import '@remoteoss/remote-flows/styles.css';\n```\n\n### Theme Customization\n\n```tsx\n\u003cRemoteFlows\n  theme={{\n    spacing: '0.25rem',\n    borderRadius: '0px',\n    colors: {\n      primaryBackground: '#ffffff',\n      primaryForeground: '#364452',\n      accentBackground: '#e3e9ef',\n      accentForeground: '#0f1419',\n      danger: '#d92020',\n      borderInput: '#cccccc',\n    },\n  }}\n\u003e\n  {/* Your components */}\n\u003c/RemoteFlows\u003e\n```\n\n| **Token**                  | **Description**                                                                                       |\n| -------------------------- | ----------------------------------------------------------------------------------------------------- |\n| `colors.borderInput`       | Border color for input fields.                                                                        |\n| `colors.primaryBackground` | Background used for the popover options                                                               |\n| `colors.primaryForeground` | Color text for the input and options                                                                  |\n| `colors.accentBackground`  | Used in the option selected and hover.                                                                |\n| `colors.accentForeground`  | Color text for the select options                                                                     |\n| `colors.danger`            | Red color used for danger states.                                                                     |\n| `spacing`                  | Consistent scale for whitespace (margin, padding, gap).                                               |\n| `borderRadius`             | The main border radius value (default: 0.625rem). This is the foundation for all other radius values. |\n| `font.fontSizeBase`        | The main font size value (default: 1rem). Controls the base text size of the component.               |\n\n### Custom CSS\n\nAll components expose CSS classes prefixed with `RemoteFlows__` for targeted styling:\n\n**Example:** Customize the Cost Calculator layout:\n\n```css\n.RemoteFlows__CostCalculatorForm {\n  display: grid;\n  grid-template-columns: 1fr 1fr;\n  gap: 1rem;\n}\n\n.RemoteFlows__SelectField__Item__country {\n  grid-column: span 2;\n}\n\n.RemoteFlows__CostCalculatorForm .RemoteFlows__Button {\n  grid-column: span 2;\n}\n```\n\n## Advanced Usage\n\nFor complete control over rendering, use our hooks directly. They handle the business logic while you control the UI:\n\n```tsx\nimport { useCostCalculator } from '@remoteoss/remote-flows';\n\nfunction CustomCostCalculator() {\n  const {\n    onSubmit: submitCostCalculator,\n    fields, // Field definitions from json-schema-form\n    validationSchema,\n  } = useCostCalculator();\n\n  return (\n    \u003cform onSubmit={handleSubmit((data) =\u003e submitCostCalculator(data))}\u003e\n      {/* Your custom form implementation */}\n    \u003c/form\u003e\n  );\n}\n```\n\nLearn more about field definitions in the [json-schema-form documentation](https://github.com/remoteoss/json-schema-form).\n\n## Example\n\nFor a complete implementation example, see our [example application](https://github.com/remoteoss/remote-flows/blob/main/example/src/App.tsx).\n\n## Contributing\n\nWe welcome contributions! If you're working on this package:\n\n- See [DEVELOPMENT.md](./DEVELOPMENT.md) for development setup, testing, and bundle size management\n- Check out our [example app](./example) to test changes locally\n- Ensure bundle size stays within limits before submitting PRs\n\n## Internals\n\nWe have created an entry point in the package `@remoteoss/remote-flows/internals`\n\nThis entry endpoint exports internals utils and shadcn components to avoid duplicating these on the `example` folder.\n\nWe don't guarantee `semver` compatiblity if you used them in your project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fremoteoss%2Fremote-flows","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fremoteoss%2Fremote-flows","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fremoteoss%2Fremote-flows/lists"}