{"id":15062432,"url":"https://github.com/fusionauth/fusionauth-astro-components","last_synced_at":"2025-04-10T13:13:29.361Z","repository":{"id":204530816,"uuid":"709833124","full_name":"FusionAuth/fusionauth-astro-components","owner":"FusionAuth","description":"Astro component to pull in remote values or code at build time","archived":false,"fork":false,"pushed_at":"2025-03-31T18:39:54.000Z","size":673,"stargazers_count":5,"open_issues_count":7,"forks_count":0,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-01T16:56:41.466Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Astro","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FusionAuth.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-25T13:42:07.000Z","updated_at":"2025-03-07T18:23:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"2601f0a1-0db7-4f24-9d04-ba9ae3be14f6","html_url":"https://github.com/FusionAuth/fusionauth-astro-components","commit_stats":null,"previous_names":["fusionauth/fusionauth-astro-components"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FusionAuth%2Ffusionauth-astro-components","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FusionAuth%2Ffusionauth-astro-components/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FusionAuth%2Ffusionauth-astro-components/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FusionAuth%2Ffusionauth-astro-components/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FusionAuth","download_url":"https://codeload.github.com/FusionAuth/fusionauth-astro-components/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248225653,"owners_count":21068078,"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","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":"2024-09-24T23:36:03.909Z","updated_at":"2025-04-10T13:13:28.756Z","avatar_url":"https://github.com/FusionAuth.png","language":"Astro","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `@fusionauth/astro-components`\n\nThis is a set of components developed by FusionAuth while creating [our docs](https://fusionauth.io)\nwith [Astro](https://astro.build/).\n\n```mdx\nimport { RemoteCode, RemoteValue } from '@fusionauth/astro-components';\n\n# This will render a \u003cCode\u003e component with the contents of that file\n\u003cRemoteCode lang=\"javascript\" url=\"https://example.com/file.js\"/\u003e\n\n# This will extract the username from the JSON file and display it\nYou are going to log in as \u003cRemoteValue url=\"https://example.com/file.json\" selector=\"$.user.username\" /\u003e.\n```\n\n# Installation\n\nInstall it via npm:\n\n```shell\n$ npm install @fusionauth/astro-components\n```\n\n\u003e These components were tested with both versions 2 and 3 of Astro.\n\n# Components\n\n## `\u003cRemoteCode\u003e`\n\nUse this to display a `\u003cCode\u003e`\ncomponent [to provide syntax highlight](https://docs.astro.build/en/guides/markdown-content/#syntax-highlighting) for\ncontent that is actually hosted somewhere else (e.g. GitHub).\n\n### Usage\n\n```mdx\nimport { RemoteCode } from '@fusionauth/astro-components';\n\n\u003cRemoteCode lang=\"json\" url=\"https://example.com/file.json\"/\u003e\n```\n\nThis is equivalent to rendering a `\u003cCode lang=\"json\" code=\"...\" /\u003e` with the contents of that JSON file.\n\n### Props\n\n- `url` (required): address with the file to download.\n- `lang` (optional): language for the code (default: `plaintext`).\n- `title` (optional): title of the section, shown as a piece of text above the block.\n- `tags` (optional): tags to extract specific lines from the file.\n  See [Lines selection by Tags](#selecting-lines-via-tags).\n\nAny other prop will be forwarded to the underlying `\u003cCode\u003e` component.\n\n### Selecting Lines\n\nThis component can retrieve some lines from the remote file according to a custom selection.\n\n#### Selecting Lines via Query String\n\nIf you just want to show some specific lines, you can pass an argument to the query string like `#L\u003cstart\u003e-L\u003cend\u003e`.\n\nExample:\n\n```mdx\n\u003cRemoteCode lang=\"javascript\" url=\"https://example.com/file.js#L9-L12\"/\u003e\n```\n\nIt will only render lines 9, 10, 11, and 12 from the file.\n\n\u003e Tip: this is the same syntax used by GitHub to mark lines in the UI.\n\n#### Selecting Lines via Tags\n\nIf you own the remote file to be injected, you can add a few comments to mark which lines you want to show, and then\npass a `tags=\"tag-name\"` property to the component, which will render lines between `tag::tag-name` and `end::tag-name`.\n\nFor instance, if you have the file below:\n\n```javascript\nconst express = require('express');\nconst app = express();\n\n// tag::listen\napp.listen(3000, () =\u003e {\n  console.log('App listening on port 3000');\n});\n// end::listen\n```\n\nTo render those lines for the `listen` function and its callback, write your code like this.\n\n```mdx\n\u003cRemoteCode lang=\"javascript\" url=\"https://example.com/file.js\" tags=\"listen\"/\u003e\n```\n\n## `\u003cRemoteValue\u003e`\n\nInstead of hard-coding values from an external file (e.g. some file from the demo app you are writing about), you can\nuse the `\u003cRemoteValue\u003e` component to render a specific value from that file.\n\n### Usage\n\nA simple usage example for the component (which will cover most cases) is when you have the following JSON file hosted\nsomewhere (e.g. GitHub) and you are writing a doc that mentions that user.\n\n```json\n{\n  \"user\": {\n    \"email\": \"richard.hendricks@example.com\",\n    \"username\": \"richard.hendricks\",\n    \"role\": \"user\"\n  }\n}\n```\n\nInstead of hard-coding the value `richard.hendricks` and taking the risk of your remote file being out-of-sync with your\ndocument, you can use:\n\n```mdx\nimport { RemoteValue } from '@fusionauth/astro-components';\n\nYou are going to log in as \u003cRemoteValue url=\"https://example.com/file.json\" selector=\"$.user.username\" /\u003e.\n```\n\nThis will extract the username from that JSON value and render this instead:\n\n```\nYou are going to log in as richard.hendricks.\n```\n\n\u003e Read more about [Selectors](#Selectors).\n\n### Props\n\n* `url` (required): remote URL to fetch the file from\n* `selector` (required): parser-dependent syntax to extract the value from the remote file\n* `parser` (optional): value from the `Parser` enum object exported by the component\n    * If not defined, the component will use the file extension from the URL\n* `defaultValue` (optional): default value if we cannot retrieve the element (otherwise, we'll render \"unknown\")\n    * This is recommended in case you ever change the remote file and the selector doesn't work anymore.\n\n#### Parsers\n\nCurrently, we only support JSON files, but the component is ready to support other extensions in the future (e.g. YAML\nor XML files), so in the future we could have something like this:\n\n```mdx\nimport { RemoteValue, RemoteValueParser } from '@fusionauth/astro-components';\n\n\u003cRemoteValue url=\"https://example.com/file.yaml\"\n             parser={Parser.YAML}\n             selector=\"some.yaml.selector.in.the.future\"\n/\u003e\n```\n\n#### Selectors\n\nThe `selector` can either be a `string` or a `function`.\n\n##### Selector Strings\n\nWhen using selector strings, you need to check the specific documentation for the parser we use. As we only have JSON right now,\nplease check [`jsonpath-plus`](https://www.npmjs.com/package/jsonpath-plus), which implements an XPath-based syntax.\n\n##### Selector Functions\n\nWhen using selector functions, we'll pass the parsed file (e.g. the JSON object) as an argument and the function should return\nthe value.\n\n##### Selector Examples\n\nThese elements will render the same value:\n\n```mdx\n\u003cRemoteValue url=\"https://example.com/file.json\"\n             selector={(element) =\u003e element.users.find(e =\u003e e.role === 'user').username}\n/\u003e\n\n\u003cRemoteValue url=\"https://example.com/file.json\"\n             selector=\"$.users.[?(@.role === 'user')].username\"\n/\u003e\n```\n\n### Common rendering scenarios\n\n#### Rendering inside custom components\n\nIf you need to render a custom component, you can use [`astro`'s way of passing callback as a child](https://docs.astro.build/en/reference/api-reference/#astroslotsrender):\n\n```mdx\n\u003cRemoteValue\n  url=\"https://example.com/file.json\"\n  selector=\"$.variables.clientId\"\u003e\n  {(value) =\u003e \u003cCode lang=\"shell\" code={`CLIENT_ID=${value} some-command`}/\u003e}\n\u003c/RemoteValue\u003e\n```\n\nThis is specially useful when you need to fetch several values and render them all in the same component:\n\n\n```mdx\n\u003cRemoteValue\n  url=\"https://example.com/file.json\"\n  selector=\"$.variables\"\u003e\n  {(vars) =\u003e \u003cCode lang=\"shell\" code={`CLIENT_ID=${vars.clientId} CLIENT_SECRET=${vars.clientSecret} some-command`}/\u003e}\n\u003c/RemoteValue\u003e\n```\n\n#### Rendering inside backticks\n\nRendering inside inline backticks won't work, but you can use standard `\u003ccode\u003e` elements instead.\n\n```mdx\n# This won't work\n`\u003cRemoteValue url=\"...\"/\u003e`\n\n# Use this instead:\n\u003ccode\u003e\u003cRemoteValue url=\"...\" /\u003e\u003c/code\u003e\n```\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub.\n\n## License\n\nThis code is available as open source under the terms of the [Apache v2.0 License](https://opensource.org/licenses/Apache-2.0).\n\n## Support\n\nThis is created and maintained with love by [FusionAuth](https://fusionauth.io), the customer authentication and\nauthorization platform that makes developers' lives awesome.\n\n# Changelog\n\n## 2.1.0\n- Components will now throw an `Error` if the fetch of the `url` fails. This is to prevent silent failures when the URL is wrong or the server is down. \n\n## 2.0.0\n- Update to be compatible with Astro 4\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffusionauth%2Ffusionauth-astro-components","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffusionauth%2Ffusionauth-astro-components","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffusionauth%2Ffusionauth-astro-components/lists"}