{"id":22914461,"url":"https://github.com/communitysolidserver/hello-world-component","last_synced_at":"2025-05-12T13:44:11.824Z","repository":{"id":103396446,"uuid":"517974915","full_name":"CommunitySolidServer/hello-world-component","owner":"CommunitySolidServer","description":"An example repository showing how to create a new component","archived":false,"fork":false,"pushed_at":"2025-03-24T07:29:01.000Z","size":835,"stargazers_count":6,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-31T22:41:25.597Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/CommunitySolidServer.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2022-07-26T08:23:24.000Z","updated_at":"2025-03-24T07:29:05.000Z","dependencies_parsed_at":"2024-02-07T06:46:54.444Z","dependency_job_id":null,"html_url":"https://github.com/CommunitySolidServer/hello-world-component","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CommunitySolidServer%2Fhello-world-component","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CommunitySolidServer%2Fhello-world-component/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CommunitySolidServer%2Fhello-world-component/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CommunitySolidServer%2Fhello-world-component/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CommunitySolidServer","download_url":"https://codeload.github.com/CommunitySolidServer/hello-world-component/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253749691,"owners_count":21958168,"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-12-14T05:15:08.703Z","updated_at":"2025-05-12T13:44:11.802Z","avatar_url":"https://github.com/CommunitySolidServer.png","language":"TypeScript","readme":"# Hello World component\n\nA Hello World component that can be injected into a \n[Community Solid Server](https://github.com/CommunitySolidServer/CommunitySolidServer/) (CSS) instance\nusing [Components.js](https://github.com/LinkedSoftwareDependencies/Components.js/).\nIt logs a message when called, and its configuration injects it into CSS\nso that it is called every time the server starts.\n\nThis repository can be used as an example of how to create a new component for CSS.\nMany different repository structures are possible,\nthe one used here is just an example.\n\nThe major version of this repository corresponds to the CSS major version it supports.\n\nInstead of copying this repository,\nthere is also a CLI tool that sets up a repository using the templates here, and more,\nat \u003chttps://github.com/liquid-surf/css-component-generator\u003e.\n\nBelow we go over all the files in the repository and how they relate to the component.\n\n## tsconfig.json\nYou can configure your TypeScript project in any way you want,\nbut to be able to reuse most of this example repository,\nyou will want to keep the `\"outDir\": \"dist\"` setting,\nwhich makes it so all generated files are created in the `dist` folder.\n\n## package.json\nContains all the important Components.js configurations. \nYou will want to update this file according to your project needs, such as name, repository, version and so on.\n\n### Components.js fields\nAll fields below are used to allow Components.js to discover everything about your project,\nand will have to be updated.\n\n`lsd:module` tells Components.js what the identifier is of your module.\n\n`lsd:components` tells Components.js where it can find an RDF description of all components created in your project.\nIf you keep the structure of this project this value can stay the same.\n\n`lsd:contexts` tells Components.js which contexts to use to interpret the component descriptions in this project,\nand where to find them.\n\n`lsd:importPaths` tells Components.js how to convert certain URLs to file paths. \nThis means that if you add a new folder to your project that contains files relevant for Components.js,\nit will need to be added here.\nBut if you use the same structure as this project these entries are enough as they describe (in order):\n * Where to find the context.\n * Where to find custom configurations.\n * Where to find the descriptions of all the classes.\n\nWhen creating your own project you will need to update all the URLs above and replace `hello-world-module`\nwith your own package name, and the version number with your version number.\nNote that Components.js only uses major version number, so the URL will always contain `x.0.0`,\neven if your version number is `x.y.z`.\n\n### Scripts\nThere are several helper scripts here such as `start` to start the server with the given settings and config,\nand `build` to both build the TypeScript and Components.js files.\n\nThe script that you will want to change is `build:components`,\nspecifically the `-r` flag which determines which prefix will be used in the generated configurations.\nAll field descriptions can be found [here](https://github.com/LinkedSoftwareDependencies/Components-Generator.js#usage).\n\n## .componentsignore\nThere are sometimes classes the Components.js generator has difficulties with to interpret.\nOften these are references to default Node.js classes or from external dependencies that do not use Components.js.\nSuch classes can be added as strings to the array in this file so they can be ignored.\nYou can see this file being referenced in the `build:components` script mentioned above.\n\n## src\nThis folder should contain all the source code of your project. Subfolders are allowed.\nOne thing that is important and often forgotten is that you need to have an `index.ts`\nthat exports **all** classes defined in your project.\nThe Components.js generator will use to file to generate its descriptions,\nso if it's not in there the generator does not know it exists.\n\n### src/HelloWorld.ts\nIn general when creating a class to inject into CSS, \nyou will want to extend an interface/abstract class from the main repository.\nWhich one depends on what you want to do and where your component would fit into the architecture.\nSome more information about the architecture can be found in \nthe CSS [documentation](https://communitysolidserver.github.io/CommunitySolidServer/).\n\nIn this specific case we wanted something to happen during server startup, so we extended `Initializer`.\nJust extending the correct interface is not enough though, it also needs to be added through configuration.\nMore on this below.\n\n## config\nHere we put all instantiations and configurations of our created components. Subfolders are allowed.\nFor more information on how to configure Components.js components we refer to both \nthe Components.js [documentation](https://componentsjs.readthedocs.io/)\nand the CSS [documentation](https://communitysolidserver.github.io/CommunitySolidServer/).\n\nNote that the files here are not required to make this repository a valid Components.js project,\nbut they do make it much easier when other people want to make use of your component\nso they do not have to configure everything themselves.\n\n### config/hello-world.json\nSince this project only has 1 small class with no parameters,\nthe configuration simply initializes that 1 class and assigns it a unique identifier.\nWe import our own new context at the top so Component.js recognizes our new class.\nIt knows where to find this context due to the fields added in the `package.json` above.\nNote that this identifier does not have to start with `urn:` or look like that,\nany valid URI is accepted.\n\n## hello-world-file.json\nThis file is used as a single example on how to start a CSS instance,\ninjected with the new component.\nSince there are so many ways to configure CSS, it is impossible to cover everything,\nbut this should already give a clear example to other users on what needs to be configured to add the new component.\n\nIn this case, we started from the `file.json` configuration of CSS. \nWe imported our own custom configuration to have access to the instantiation of our new class.\nWe then add that instantiation to the list of Initializers that get executed when the server starts.\n\nSomething that is easily missed is that at the top of this configuration, we are now importing 2 contexts:\nour own new context, and the original one from CSS.\n\nThis file can also be combined with the CSS configuration tool as described \n[here](https://github.com/CommunitySolidServer/configuration-generator/).\nFor example, you can generate configurations that already include the necessary extra lines to add the new component\n[here](https://communitysolidserver.github.io/configuration-generator/v7/?config=https%3A%2F%2Fraw.githubusercontent.com%2FCommunitySolidServer%2Fhello-world-component%2Fmain%2Fhello-world-file.json).\n\n## hello-world-partial.json\nSimilar to hello-world-file.json this configuration defines how the new component is added to a CSS instance.\nThe difference being that this one lacks all the necessary imports.\nThis can be combined with an already existing CSS configuration\nby providing both as config parameters when starting CSS.\nAn example of the difference can be seen in the `start` and `start-alt` scripts in the `package.json`.\n\nSuch a configuration can also be injected into the configuration tool as can be seen\n[here](https://communitysolidserver.github.io/configuration-generator/v7/?config=https%3A%2F%2Fraw.githubusercontent.com%2FCommunitySolidServer%2Fhello-world-component%2Fmain%2Fhello-world-partial.json).\n\n## test\nAn important part of creating a new component is testing to make sure everything works correctly.\nFor this we make use of the [jest](https://jestjs.io/) test framework,\nbut any test framework that has TypeScript support can be used.\n\n### test/config/hello-world-memory.json\nThis is a configuration file that is used to test a server running with our new component.\nIt is very similar to the `hello-world-file.json` from above,\nbut configured so that everything is stored in memory, to prevent writing files during tests,\nand so that the server immediately initializes on startup so no manual setup is needed.\n\n### test/integration/Server.test.ts\nOne thing we want to test is if the server with our new component behaves as expected.\nThis integration test sets up a complete and running CSS instance and performs an HTTP request to see the response.\nMore details on how this happens can be found in the file itself.\n\n### test/unit/HelloWorld.test.ts\nTo make sure all our individual classes do what we want them to do,\nwe need to have unit tests to test all possible situations.\nIn this case we make sure the logger gets called with the correct string.\n\n### jest.config.js\nA minimal jest configuration.\nTo extend this, see https://jestjs.io/docs/configuration.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommunitysolidserver%2Fhello-world-component","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcommunitysolidserver%2Fhello-world-component","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommunitysolidserver%2Fhello-world-component/lists"}