Some Questions about how to create an App Extension

[rdonadeu]

I've been working on a project for a year and now I will start in the same company more separate projects, so i want to reuse some components. I would like to create a component npm package.

I've been reading the docs: https://quasar.dev/app-extensions/development-guide/introduction

but I have a lot of questions.

Why do I have two folders?
'app-extension'
'ui'

I suppose that app-extension is the one that will be published and used on my quasar project. But it has a dependency on the ui one.

So I have to work on the ui one, then publish it and then update app-extension and publish it too?

Also in the docs https://quasar.dev/app-extensions/tips-and-tricks/provide-a-ui-component, when it shows a folder structure I don't know to which of the two folders is talking about because both folders have a different structure than the one defined here.

To me it looks like It's the app-extension one. As it contains an index.js and register.js, but it doesn't makes sense?

I tried creating a button component to test if it works and I'm not able to make it work.

<template>
  <q-btn :label="label" color="primary"></q-btn>
</template>
<script>
import { QBtn } from "quasar";
export default {
  name: "MyButton",
  props: {
    label: {
      type: String,
      required: true,
      default: "label",
    },
  },
  components: {
    QBtn,
  },
};
</script>

What I don't understand is, If i have to create here the button, why does this file 'register.js' imports quasar-ui-my-components

import VuePlugin from "quasar-ui-my-components";
import { boot } from "quasar/wrappers";
import { Button } from "../Button/Button.vue";

export default boot(({ app }) => {
  app.use(VuePlugin);
  app.component("my-button", Button);
});

When I add the package as App expansion to my project with 'quasar ext add my-components', I can't use my component. I can't even use the example component that autogenerates with the project

import { QBadge } from 'quasar'
import { h } from 'vue'

export default {
  name: 'KettalComponents',

  setup () {
    return () => h(QBadge, {
      class: 'KettalComponents',
      label: 'KettalComponents'
    })
  }
}

<KettalComponents></KettalComponents>

[Vue warn]: Failed to resolve component: KettalComponents
If this is a native custom element, make sure to exclude it from component resolution via compilerOptions.isCustomElement. 
  at <LayoutMainMenu onVnodeUnmounted=fn<onVnodeUnmounted> ref=Ref< Proxy(Object) {$i18n: {…}, $t: ƒ, $rt: ƒ, $tc: ƒ, $te: ƒ, …} > > 
  at <RouterView> 
  at <App>

[rdonadeu]

UPDATE

It finally works but I used only app-extension folder. and removed dependenci on ui folder.
I created the component, then import it in register.js and that's all.

[yusufkandemir]

I've been reading the docs: https://quasar.dev/app-extensions/development-guide/introduction

but I have a lot of questions.

Why do I have two folders?
'app-extension'
'ui'

If you read the docs, you will see this:

An App Extension is an npm package. There are two official kits for creating App Extensions:

• App Extension (AE) kit
• UI kit

App Extension (AE) kit
If your app extension does not involve UI (i.e. does not have components or directives) then use the AE kit. An example of this would be an extension that creates a boot file only.

UI kit
If your app extension does involve UI (i.e. does have components or directives) then use the UI kit. An example of this would be an extension that provides a UI element for use in your app. This has a ui folder for creating your component/directive, a ui/dev Quasar application for testing your component/directive in isolation, and an app-extension folder for creating the App Extension that will be used for injecting your component/directive via the Quasar CLI into a Quasar app. The UI kit can also be used such that your component/directive can also be used with the Quasar Vite plugin or Vue CLI or UMD.

...

When using the UI kit, you will have two npm packages; one for the App Extension and one for the UI module. For testing with the dev app, from the ui folder type yarn dev. Create pages in the dev folder for testing and they will automatically be injected into the test app. Also, check out the scripts section in the package.json to see what you have available. When you yarn build, a dist folder will be created and populated with various types of packages (common, esm, and umd).

Also in the docs https://quasar.dev/app-extensions/tips-and-tricks/provide-a-ui-component, when it shows a folder structure I don't know to which of the two folders is talking about because both folders have a different structure than the one defined here.

That's an older page that was written before the UI kit was a thing. It can still be used for simple projects where you don't care about extra DX or the ability to use outside Quasar CLI, e.g. UMD, vite-plugin, etc.

So, to sum up, when you are working with UI stuff, e.g. components, use the UI kit. UI kit has a better DX(better build system, dev playground, etc.) and is more flexible(being able to use outside Quasar CLI). Your components live inside ui/src/components, they can be exported from ui/src/index.esm.js, and/or can be installed automatically in ui/src /vue-plugin.js. app-extension/src/boot/register.js is used to import your UI package and install the Vue plugin so that the people who install the AE doesn't have to install or configure your UI package separately.

[rdonadeu]

yes, i know, but i don't understand why I need both packages, wouldn't be easier to have just the UI folder and then publish that package only? With two folders I have to publish both each time I make an update. Anyway, I'll close this topic as I made it work and your reponse answers my questions. Thanks

[yusufkandemir]

You can't modify quasar.config, extend Vite config, create boot files, auto-register components, etc. with just the UI folder. If your library just consists of basic components, and you are fine with installing/importing it manually in your app, then you can just go with the UI package and interact with it directly, rather than installing the AE package.

[rdonadeu]

As I tried to add the components to UI instead of in app-extension, I can't build the ui folder.

I have this component:

<template>
  <div class="popup" v-if="isOpen" test-id="commonPopup">
    <div
      class="popup__background"
      v-on:click="handleClickOutsidePopup"
      test-id="popupBackground"
    ></div>
    <div class="popup__container">
      <div class="popup__header row justify-between no-wrap items-center">
        <div class="popup__title" test-id="popupTitle">{{ popupTitle }}</div>
        <div
          class="popup__btnClose"
          test-id="popup__btnClose"
          v-on:click="$emit('closePopup')"
        >
          <q-icon class="close__icon">
            <img src="../../assets/icons/Exit.svg"
          /></q-icon>
        </div>
      </div>

      <div class="popup__parentContent" test-id="popupContent">
        <slot></slot>
      </div>
    </div>
  </div>
</template>

<style scoped>
.close__icon {
  width: 1.5rem;
  height: 1.5rem;
}
.popup {
  position: absolute;
  width: 100%;
  height: 100%;
  top: 0;
  left: 0;
  z-index: 3000;
  display: flex;
  align-items: center;
  justify-content: center;
}
.popup__background {
  background-color: rgba(0, 0, 0, 0.3);
  position: absolute;
  height: 100%;
  width: 100%;
}

.popup__container {
  background-color: white;
  z-index: 4000;
  position: absolute;
  margin: auto;
  overflow: scroll;
  max-width: 95%;
  max-height: 95%;
}

.popup__parentContent {
  padding: 0rem 2rem 2rem 2rem;
}

.popup__header {
  margin: 1rem 2rem;
  gap: 5rem;
  position: sticky;
  top: 0;
  z-index: 1000;
  background-color: white;
  height: 3rem;
  font-size: 1.5rem;
}

.popup__btnClose {
  cursor: pointer;
  text-align: right;
}

.popup__btnClose span {
  display: block;
  width: 30px;
  height: 30px;
  background-position: center;
  background-repeat: no-repeat;
  background-size: contain;
  cursor: pointer;
  margin-left: auto;
}
@media only screen and (max-width: 1024px) {
  .popup__container {
    max-width: 90%;
    max-height: 90%;
    margin: 1rem;
  }
}
</style>

<script>
import { defineComponent } from "vue";
export default defineComponent({
  name: "CommonPopup",
  props: {
    /** Indicates if popup is open */
    isOpen: {
      type: Boolean,
      required: true,
    },
    /** Title of the popup */
    popupTitle: {
      type: String,
      required: false,
    },
    /** Allow the popup to close when clicking on the background */
    persistent: {
      type: Boolean,
      required: false,
      default: false,
    },
  },
  methods: {
    /**
     * Closes the popup when clicked outside
     *
     * v-on:public
     */
    handleClickOutsidePopup() {
      if (!this.persistent) {
        this.$emit("closePopup");
      }
    },
  },
});
</script>

And when trying to build it it says:
SyntaxError: Adjacent JSX elements must be wrapped in an enclosing tag (29:0)

I suppose this is because Single-file components are not allowed in this build. And i don't know how to add a sfc plugin builder as this doesn't work with babel or webpack.

[yusufkandemir]

I suppose this is because Single-file components are not allowed in this build.

Yes, that's correct. I believe there should be examples of an advanced build system somewhere in the community. We are also planning to improve the build system of AE/UI kit templates. If you don't want to bother with build configuration and you are totally fine with just using your components in Quasar CLI apps and no intent of sharing your package, then you should probably go with the AE template for this thing.

[rdonadeu]

Yes I don't plan to share it, just use it in my comppany across multiple project with smae UI. I'll use AE folder then. Thanks!