Nuclia UI starter

Start building your own Svelte application using Nuclia’s search capabilities and UI tools.

Installation

First you need to either download and uncompress the zip file directly from the repository or clone it by doing:

git clone https://github.com/nuclia/ui-starter.git

Then, install dependencies:

cd ui-starter
npm install
npm run missdev

You may have noticed the last step npm run missdev which might be unusual to you. mrs-developer is a NodeJS utility providing the command missdev which makes it easy to work with external source code locally, as it allows to replace any given dependency with a checkout from its Git repository.

We're using missdev to load and have access to Nuclia’s frontend dependencies:

• @nuclia/core: SDK allowing to integrate Nuclia services in your frontend application
• @nuclia/ui: Svelte components and web components allowing to use Nuclia’s search capabilities
• @nuclia/prediction: library used by Nuclia’s SearchBar widget

The starter is a SvelteKit application including:

• a simple layout allowing to navigate between the pages
• a page showing a simple example of Nuclia’s widgets integration
• a page showing an example of how Nuclia’s NucliaSearchResults widget works, loading API results without using the NucliaSearchBar widget.
• a page showing Nuclia‘s widgets dark mode
• a page showing how to customize Nuclia‘s widgets style
• a page showing how to easily add a breadcrumb above result rows

Developing

Once you've cloned the project and installed dependencies, start a development server:

npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open

The app is then available on http://localhost:5173/.

Building

To create a production version of your app:

npm run build

You can preview the production build with npm run preview.

To deploy your app, you may need to install an adapter for your target environment.

Compile your own Nuclia widget

Note: all theses steps are already implemented in this repository, but we detail them here so you can reproduce them in your own project.

• Create a new folder src/widgets/my-widget (my-widget is just how we named it in our example, you are free to choose any name, just make sure to use the same name everywhere in the following steps and in custom.vite.config.mjs)

• Copy all files from libs/nuclia/libs/search-widget/src/widgets/search-widget/ to src/widgets/my-widget

• In the 2 Svelte files:

  • Fix the globalCss import:

    import globalCss from '../../../libs/nuclia/libs/search-widget/src/common/_global.scss?inline';
    

  • Replace all the other relative imports starting with ../.. by @nuclia/ui, like:

    import { loadFonts, loadSvgSprite, setCDN } from '../../core/utils';
    

    becomes

    import { loadFonts, loadSvgSprite, setCDN } from '@nuclia/ui';
    

    Be careful with default imports, like:

    import SearchInput from '../../components/search-input/SearchInput.svelte';
    

    will become

    import { SearchInput } from '@nuclia/ui';
    

  • In SearchBar.svelte, fix the <style> tag at the end:

    <style
      lang="scss"
      src="../../../libs/nuclia/libs/search-widget/src/common/common-style.scss"
    ></style>
    

  • In SearchResults.scss, fix the import path similarly:

    @import '../../../libs/nuclia/libs/search-widget/src/common/common-style';
    

• Implement your components in src/components/ and use them in your widget.

  In our example, we added src/components/CreationDate.svelte, implementing a component displaying the creation date of a resource. It is imported in src/widgets/my-widget/SearchResults.svelte:

  import CreationDate from '../../components/CreationDate.svelte';
  

  and inserted in the template just before the existing ResultRow component:

  <CreationDate date="{result.created}" />
  <ResultRow {result} />
  

  Note: In this case, we are just adding a new component, but you are free to copy and adapt an existing one like ResultRow to your needs. You will just need to import it from ../../components/ instead of @nuclia/ui.

• You can see the result in dev mode in your browser by running:

  npm run dev
  

  and go to http://localhost:5173/custom-widget to debug and tune your changes.

• When you are done, build the widget with:

  npx vite build -c=custom.vite.config.mjs
  

  This will create a dist/my-widget folder containing the compiled widget.

You can now use your widget in any web page as follow:

<script src="./dist/my-widget/widget.umd.cjs"></script>
<nuclia-search-bar
  knowledgebox="YOUR-KB-ID"
  zone="YOUR-ZONE"
  features="answers,permalink"
  placeholder="Enter your question or search terms"
></nuclia-search-bar>
<nuclia-search-results> </nuclia-search-results>